afs.cmd: Add documentation of all blob commands.
[paraslash.git] / afs.cmd
1 OF: afs_command_list
2 SF: afs.c aft.c attribute.c
3 HC: Prototypes for the commands of the audio file selector.
4 CC: Array of commands for the audio file selector.
5 AT: server_command
6 IN: para afh server list user_list
7 SN: list of afs commands
8 TM: mood lyr img pl
9 ---
10 N: add
12 D: Add new audio files to the database.
13 U: add [-l] [-f] [-v] path1 ...
14 H: Each given path may be either the full path to an audio file, or the full path
15 H: of a directory. In case of a directory, all audio files in that directory
16 H: are added recursively.
17 H:
18 H: Options:
19 H:
20 H: -l Add files lazily. If a file already exists in the database, skip this file.
21 H: This operation is really cheap. Use it when adding large directories if only a
22 H: few files where added.
23 H:
24 H:-f Force adding/updating. Recompute the audio format handler data
25 H: even if a file with the same path and the same hash value exists.
26 H:
27 H: -v Verbose mode. Print what is being done.
28 ---
29 N: init
31 D: Initialize the osl tables for the audio file selector.
32 U: init [table_name ...]
33 H: When invoked without arguments, this command creates all tables. Otherwise
34 H: only the tables given by table_name... are created.
35 ---
36 N: afs_ls
38 D: List audio files.
39 U: ls [-l[s|l|v|m]] -p -a -r -s{p|s|l|n|f|c|i|y|b|d|a} [pattern ...]
40 H: Print a list of all audio files matching pattern.
41 H:
42 H: Options:
43 H: -l Change listing mode. Defaults to short listing if not given.
44 H: -ls: short listing mode
45 H: -ll: long listing mode (equivalent to -l)
46 H: -lv: verbose listing mode
47 H: -lm: mbox listing mode
48 H:
49 H: -p List full path of audio file. If not specified, only the basename
50 H: of each file is printed.
51 H:
52 H: -a List only file that are admissible with respect to the current mood or
53 H: playlist.
54 H:
55 H: -r Reverse sort order.
56 H:
57 H: -s Change sort order. Defaults to alphabetical path sort if not given.
58 H: -sp: sort by path.
59 H: -sl: sort by last played time.
60 H: -ss: sort by score (implies -a).
61 H: -sn: sort by number of times the file was played.
62 H: -sf: sort by frequency.
63 H: -sc: sort by number of channels.
64 H: -si: sort by image id.
65 H: -sy: sort by lyrics id.
66 H: -sb: sort by bitrate.
67 H: -sd: sort by duration.
68 H: -sa: sort by audio format.
69 ---
70 N: lsatt
72 D: List attributes
73 U: lsatt [-a] [-l]
74 H:
75 H: Print the list of all defined attributes.
76 H:
77 H: Options:
78 H: -a Sort attributes alphabetically by name. The default is to sort by
79 H: identifier.
80 H:
81 H: -l Print a long listing containing both identifier and attribute name. The
82 H: default is to print only the name.
83 ---
84 N: setatt
86 D: Set attribute(s) for all files matching a pattern.
87 U: setatt attribute1{+|-} [attribute2{+|-}...] pattern
89 H: Set ('+') or unset ('-') the given attributes for all audio files matching
90 H: pattern. Example:
91 H:
92 H: sa rock+ punk+ classic- '*foo.mp3'
93 H:
94 H: sets the 'rock' and the 'punk' attribute but unsets the 'classic'
95 H: attribute of all files ending with 'foo.mp3'.
96 ---
97 N: addatt
99 D: Add new attribute(s).
100 U: addatt attribute1 [attribute2 ...]
101 H: This adds new attributes to the attribute table. At most 64 attributes
102 H: may be defined.
103 ---
104 N: check
106 D: Run integrity checks for the osl tables.
107 U: check [-a] [-m] [-p]
108 H: FIXME
109 ---
110 N: rmatt
112 D: FIXME
113 U: FIXME
114 H: FIXME
115 ---
116 N: afs_rm
118 D: FIXME
119 U: FIXME
120 H: FIXME
121 ---
122 N: touch
124 D: Manupulate the afs data for all audio files matching a pattern.
125 U: touch [-n numplayed] [-l lastplayed] [-y lyrics_id] [-i image_id] pattern
126 If neither of the optional options is given, lastplayed is set to the current
127 time and numplayed is increased by one. Otherwise, only the given options are
128 taken into account.
129 Options:
130 H: -n Set numplayed count. The number of times afs has selected this
131 H: audio file for streaming.
132 H:
133 H: -l Set lastplayed time. The last time this audio file was selected.
134 H: Must be given as the number of sectonds since the epoch. Example:
135 H:
136 H: touch -l $(date +%s) file
137 H:
138 H: sets the lastplayed time of 'file' to the current time
139 H:
140 H: -y Set the lyrics id. Specify the lyrics data file associated with
141 H: this audio file.
142 H:
143 H: -i Set the image id. Same as -y, but sets the image.
144 ---
145 T: add
146 N: add@member@
147 O: int com_add@member@(int fd, int argc, char * const * const argv);
149 D: Read data from stdin and add it as a blob to an osl table.
150 U: add@member@ @member@_name
151 H: Each command of this family reads arbitrary binary data from stdin and sends
152 H: that data to the audio file selector process. The afs process then creates a
153 H: new blob for the data in the corresponding osl table. Example:
154 H:
155 H: addimg foo.jpg < bar.jpg
156 H:
157 H: adds the contents of the file 'bar.jpg' as a blob named 'foo.jpg' to the image
158 H: table. The names of the blobs of a table must be unique, i.e. it is an error
159 H: if an entry named 'foo.jpg' already exists.
160 ---
161 T: cat
162 N: cat@member@
163 O: int com_cat@member@(int fd, int argc, char * const * const argv);
165 D: Dump the contents of a blob to stdout.
166 U: cat@member@ @member@_name
167 H: These commands may be used to retrieve the blob identified by the given name from
168 H: the corresponding osl table to which they were previously added.
169 ---
170 T: ls
171 N: ls@member@
172 O: int com_ls@member@(int fd, int argc, char * const * const argv);
174 D: List blobs of an osl table matching a pattern.
175 U: ls@member@ [-v] [pattern]
176 H: Print a list of the names of all blobs in the corresponding osl table which
177 H: match the given pattern. If no pattern is given, the full list is printed. If
178 H: the optional -v pattern is given, the blob id is printed as well.
179 ---
180 T: rm
181 N: rm@member@
182 O: int com_rm@member@(int fd, int argc, char * const * const argv);
184 D: Remove blob(s) from an osl table.
185 U: rm@member@ pattern...
186 H: Remove all blobs from the corresponding table which match any given pattern.
187 ---
188 T: mv
189 N: mv@member@
190 O: int com_mv@member@(int fd, int argc, char * const * const argv);
192 D: Rename a blob.
193 U: mv@member@ old_@member@_name new_@member@_name
194 H: Rename the blob identified by the first name as the second name.