79b118ad79170153e19d4bd8f19c685147b1af69
[vlc.git] / share / lua / http / requests / README.txt
1 $Id$
2
3 This file describes commands available through the requests/ file:
4
5 Lines starting with < describe what the page sends back
6 Lines starting with > describe what you can send to the page
7
8 All parameters need to be URL encoded.
9 Examples:
10  # -> %23
11  % -> %25
12  + -> %2B
13  space -> +
14  ...
15
16
17 Deprecation Notice:
18 ---
19 The entire interface is moving to using <MRL> for input and output parameters and attributes
20 pl_play and in_enqueue previously accepted paths. This is still supported, but from 1.3 <MRL> will be required
21 where path attributes are provided in output, these should be ignored in favour of uri attributes
22 path support is scheduled to be removed entirely from 1.3
23 ---
24
25 <root> (/)
26 ===========
27
28
29 > Get album art for current input:
30   /art  (NB: not /requests/art)
31
32 > Get album art for any playlist input (available from API version 3):
33   /art?item=123  (NB: not /requests/art)
34
35
36 status.xml or status.json
37 ===========
38
39
40 < Get VLC status information, current item info and meta.
41 < Get VLC version, and http api version
42
43 > add <uri> to playlist and start playback:
44   ?command=in_play&input=<uri>&option=<option>
45   the option field is optional, and can have the values:
46     noaudio
47     novideo
48
49 > add <uri> to playlist:
50   ?command=in_enqueue&input=<uri>
51
52 > add subtitle to currently playing file
53   ?command=addsubtitle&val=<uri>
54
55 > play playlist item <id>. If <id> is omitted, play last active item:
56   ?command=pl_play&id=<id>
57
58 > toggle pause. If current state was 'stop', play item <id>, if no <id> specified, play current item. If no current item, play 1st item in the playlist:
59   ?command=pl_pause&id=<id>
60
61 > resume playback if paused, else do nothing
62   ?command=pl_forceresume
63
64 > pause playback, do nothing if already paused
65   ?command=pl_forcepause
66
67 > stop playback:
68   ?command=pl_stop
69
70 > jump to next item:
71   ?command=pl_next
72
73 > jump to previous item:
74   ?command=pl_previous
75
76 > delete item <id> from playlist:
77   ?command=pl_delete&id=<id>
78   NOTA BENE: pl_delete is completly UNSUPPORTED
79
80 > empty playlist:
81   ?command=pl_empty
82
83 > set audio delay
84   ?command=audiodelay&val=<delayinseconds>
85
86 > set subtitle delay
87   ?command=subdelay&val=<delayinseconds>
88
89 > set playback rate. must be > 0
90   ?command=rate&val=<newplaybackrate>
91
92 > set aspect ratio. Must be one of the following values. Any other value will reset aspect ratio to default
93   ?command=aspectratio&val=<newratio>
94   Valid aspect ratio values: 1:1 , 4:3 , 5:4 , 16:9 , 16:10 , 221:100 , 235:100 , 239:100
95
96 > sort playlist using sort mode <val> and order <id>:
97   ?command=pl_sort&id=<id>&val=<val>
98   If id=0 then items will be sorted in normal order, if id=1 they will be
99   sorted in reverse order
100   A non exhaustive list of sort modes:
101     0 Id
102     1 Name
103     3 Author
104     5 Random
105     7 Track number
106
107 > toggle random playback:
108   ?command=pl_random
109
110 > toggle loop:
111   ?command=pl_loop
112
113 > toggle repeat:
114   ?command=pl_repeat
115
116 > toggle fullscreen:
117   ?command=fullscreen
118
119 > enable services discovery module <val>:
120   ?command=pl_sd_add&val=<val>
121
122 > disable services discovery module <val>:
123   ?command=pl_sd_remove&val=<val>
124
125 > set volume level to <val> (can be absolute integer, percent or +/- relative value):
126   ?command=volume&val=<val>
127   Allowed values are of the form:
128     +<int>, -<int>, <int> or <int>%
129
130 > seek to <val>:
131   ?command=seek&val=<val>
132   Allowed values are of the form:
133     [+ or -][<int><H or h>:][<int><M or m or '>:][<int><nothing or S or s or ">]
134     or [+ or -]<int>%
135     (value between [ ] are optional, value between < > are mandatory)
136   examples:
137     1000 -> seek to the 1000th second
138     +1H:2M -> seek 1 hour and 2 minutes forward
139     -10% -> seek 10% back
140
141 >command=preamp&val=<val in dB>
142  sets the preamp value, must be >=-20 and <=20
143
144 >command=equalizer&band=<band>&val=<gain in dB, must be >=-20 and <=20)
145  set the gain for a specific band
146
147 >command=enableeq&val=<0 or 1>
148  0 --  disables the equalizer
149  1 --  enables the equalizer
150
151 >command=setpreset&val=<presetid>
152  set the equalizer preset as per the id specified
153
154 <Displays the equalizer band gains.
155 Band 0: 60 Hz, 1: 170 Hz, 2: 310 Hz, 3: 600 Hz, 4: 1 kHz,
156 5: 3 kHz, 6: 6 kHz, 7: 12 kHz , 8: 14 kHz , 9: 16 kHz
157
158 <Display the list of presets available for the equalizer
159
160 ---
161 Commands available from API version 2
162 ---
163
164 > select the title
165   ?command=title&val=<val>
166
167 > select the chapter
168   ?command=title&val=<val>
169
170 > select the audio track (use the number from the stream)
171   ?command=audio_track&val=<val>
172
173 > select the video track (use the number from the stream)
174   ?command=video_track&val=<val>
175
176 > select the sibtitle track (use the number from the stream)
177   ?command=subtitle_track&val=<val>
178
179 playlist.xml or playlist.json:
180 =============
181 < get the full playlist tree
182
183 NB: playlist_jstree.xml is used for the internal web client. It should not be relied upon by external remotes.
184 It may be removed without notice.
185
186 browse.xml or browse.json:
187 ===========
188
189 < ?dir=<uri>
190 > get file list from uri. At the moment, only local file uris are supported
191
192 NB: uri is the preferred parameter. Dir is deprecated and may be removed in a future release.
193 < ?dir=<dir>
194 > get <dir>'s filelist
195
196 vlm.xml:
197 ========
198 < get the full list of VLM elements
199
200 vlm_cmd.xml:
201 ============
202 < execute VLM command <cmd>
203   ?command=<cmd>
204 > get the error message from <cmd>
205