prefetch: don't do anything when reading 0 bytes
[vlc.git] / doc / vlm.txt
blob1ee3b194e116fb3e8b370a285f5fdbe4e0de9531
1 VLM: VideoLAN (Media) Manager
3 VLM is a little media manager originally designed to launch multiple
4 streams with only one VLC.
6 I - Interfaces
7  1) Telnet interface
8     You can launch it as a common interface.
9     Default port is 4212, default password is "admin". These are common
10     options of the interface, so you can modify them as you wish.
11     Once you are connected on telnet interface, just type a command
12     line.
14  2) HTTP interface
15     You can launch it as a common interface
16     Default port is 8080.
17     Access it from http://127.0.0.1:8080/vlm.html
19 II - VLM Elements
20  1) Medias
21     A media is composed with a list of inputs (the videos and audios you
22     want to stream), an output (where you want to stream them), and some
23     options.
24     There are two types of medias: vod and broadcast.
25     A vod media is commonly used for Video on Demand. It can be launched
26     only if a vod client asks for it.
27     A broadcast media is very close to a TV program, or channel: it is
28     launched, stopped, paused by the administrator (or a schedule), may
29     be repeated several times etc.
31  2) Schedules
32     A Schedule is a script with a date. When the current date is the
33     schedule date, the script is launched. There are of course other
34     options, like a period, a number of repetitions, etc. for the
35     schedule to be launched several times (or endlessly) automatically.
37 III - Command line syntax:
38 Note: an element is a media or a schedule.
39  1) Command lines:
40     help
41         Displays an exhaustive commmand lines list.
43     new (name) vod|broadcast|schedule [properties]
44         Creates a new element. You must specify if it as a vod media, a
45         broadcast media, or a schedule (there is no default type).
46         "media" and "schedule" are reserved names, and element names
47         must be unique.
48         Properties are optional: you can use the "setup" command to set
49         it.
50     setup (name) (properties)
51         Set the property of the (name) element.
52         See Properties section for more information.
53     show [(name)|media|schedule]
54         Displays current element states and configurations.
55         "show (name)" displays all information about the (name) element.
56         "show media" displays a summary of medias states.
57         "show schedule" displays a summary of schedules states.
58         "show" is a the same as "show media show schedule".
59     del (name)|all|media|schedule
60         Destroys an element, or a group of elements. If the element is
61         at a non-stop state, it stops it (media or schedule).
62         "del (name)" destroys the (name) element.
63         "del all" destroys all elements.
64         "del media" destroys all medias.
65         "del schedule" destroys all schedules.
66     control (name) [instance_name] (command)
67         Changes the state of the (instance_name) instance of (name) media.
68         If (instance_name) is not specified, the control command affects the
69         default instance.
70         See Commands section for more information.
71     save (config_file)
72         Saves all media and schedule configurations in the (config_file)
73         configuration file. the "save" command overwrites the file if it
74         already exists. States (playing, paused, stop) are not saved.
75         See Configuration File section for more information.
76     load (config_file)
77         Loads the (config_file) configuration file.
78         See Configuration File section for more information.
80  2) Properties:
81  Note: except the "append" property, all property can be followed by
82  another one, recursively.For example:
83  "setup pouet input file://arf.avi output udp:127.0.0.1 enabled loop"
84  is a valid command line.
85     Media Properties Syntax:
86         input (input_name)
87             Adds (input_name) at the end of the media input list.
88         inputdel (input_name)|all
89             Deletes (input_name) or all items from the media input list.
90         inputdeln (input_number)
91             Deletes the item #(input_number) from the media input list.
92         output (output_name)
93             Defines the output of the media.
94             The syntax is equivalent to the ":sout=..." option , but you
95             do not have to put the ":sout=" string.
96         option (option_name)[=value]
97             Adds the (option_name) to the media option list.
98             The syntax is equivalent to the ":(option)=..." option , but you
99             do not have to put the ":" string.
100             Options are global: they are applied to all inputs of the
101             media.
102         enabled|disabled
103             Enable or Disable the media.
104             If a media is disabled, it can not be streamed, paused,
105             launched by a schedule, or played as a VoD.
106         loop|unloop
107             Used for broadcast only.
108             If a media with "loop" option receives the "play" command
109             and finally finishes to play the last input of the list, it
110             will automatically restart to play the input list.
111         mux (mux_name)
112             Used for vod only.
113             Only needs to be specified if you want the elementary streams
114             to be sent encapsulated instead of raw. The (mux_name) should be
115             a fourcc describing the encapsulation type (eg. mp2t for MPEG TS,
116             or mp2t for MPEG PS).
118     Schedule Properties Syntax:
119         enabled|disabled
120             A disabled schedule will never be launched.
121         append (command)
122             Adds a command to the command line list.
123             The command line can be every command the VLM can understand.
124             Note: the rest of the line will be considered as part of the
125             command line. You cannot put another option after the
126             "append" one.
127         date (year)/(month)/(day)-(hour):(minutes):(seconds)|now
128             Specifies the first date the schedule should be launched.
129             the date must have the explicit form:
130             (year)/(month)/(day)-(hour):(minutes):(seconds)
131             For example: 2004/03/07-12:42:30
132             If you write "now" instead of a date, the schedule will be
133             launch as soon as possible (as soon as it is enabled), and
134             the current date will be used as the first date of the
135             schedule (for repeating).
136         period (years)/(months)/(days)-(hours):(minutes):(seconds)
137             Specifies the period of time a schedule must wait for
138             launching itself another time.
139             For now, the period has a very close syntax to a date:
140             months are considered as 30 days
141             years are considered as 12 months.
142             If a period is specified without a "repeat", it will be
143             launched endlessly.
144         repeat (number_of_repetitions)
145             Specifies the number of times the schedule has to be launch
146             again. For example, if a schedule has "repeat 3", it will be
147             launched 4 times.
149  3) Control Commands Syntax:
150     play
151         Starts a broadcast media. The media begins to launch the first
152         item of the input list, then launches the next one, and so on
153         (like a playlist).
154     pause
155         Puts the broadcast media in paused status.
156     stop
157         Stops the broadcast media.
158     seek (percentage)
159         Seeks in the current playing item of input list.
161 IV - The configuration file
162   A VLM configuration file is very simple: it is only a list of command
163   lines: one line corresponds to one command line.
164   If you want to create a configuration file, just edit a text file and
165   type a list of VLM command lines. But beware of recursive calls: you
166   can put a "load (file)" command in a configuration file, so for
167   example, if you put a "load pouet" in a pouet file, and you launch the
168   "load pouet" command, then pouet will be loaded endlessly, and VLC
169   will crash (at least).
170   The load command converts the medias and schedules configurations into
171   command lines, and writes them into a file.
172   Any line where the first non white space character is a '#' is considered
173   as a comment.