DOCS/tech/slave.txt

   1 SLAVE MODE PROTOCOL
   2 -------------------
   3
   4 The -slave option switches on slave mode, in which MPlayer works as a backend
   5 for other programs. Instead of intercepting keyboard events, MPlayer will read
   6 commands separated by a newline (\n) from stdin.
   7
   8 To try slave mode out by hand, run
   9
  10   mplayer -slave -quiet <movie>
  11
  12 and type slave commands into the console window.
  13
  14 You can also use a fifo file (named pipe):
  15
  16   mkfifo </tmp/fifofile>
  17   mplayer -slave -input file=</tmp/fifofile> <movie>
  18
  19 Most slave mode commands are equivalent to command line options, though not
  20 necessarily under the same name. Detailed descriptions can be found in the
  21 man page.
  22
  23 NOTE: the following paragraph is mostly obsolete; tricky pause handling
  24 was required in old MPlayer versions where all commands unpaused by default.
  25 Now running commands does not require leaving pause state any more, and
  26 the prefixes described here should not be required in normal use.
  27 All commands can be prefixed with one of "pausing ", "pausing_keep ", or
  28 "pausing_toggle ". "pausing " tells MPlayer to pause as soon as possible
  29 after processing the command. "pausing_keep " tells MPlayer to do so only if
  30 it was already in paused mode. "pausing_toggle " tells MPlayer to do so
  31 only if it was not already in paused mode. Please note that "as soon as
  32 possible" can be before the command is fully executed.
  33 As a temporary hack, there is also the _experimental_ "pausing_keep_force "
  34 prefix, with which MPlayer will not exit the pause loop at all.
  35 Like this you can avoid the "frame stepping" effect of "pausing_keep "
  36 but most commands will either not work at all or behave in unexpected ways.
  37 For "set_mouse_pos" and "key_down_event", "pausing_keep_force" is the default
  38 since other values do not make much sense for them.
  39
  40
  41 Various tips and tricks (please help expand it!):
  42
  43 - To ensure the user can't control MPlayer "behind your back" use
  44   something like -input nodefault-bindings -noconfig all
  45
  46
  47 Available commands ('mplayer -input cmdlist' will print a list):
  48
  49 af_add <filter_arguments_list>  (comma separated list of audio filters with parameters)
  50     (experimental) Load the given list of audio filters.
  51
  52 af_clr
  53     (experimental) Unload all loaded audio filters.
  54
  55 af_cmdline <filter_name> <filter_arguments>
  56     (experimental) Send new command-line options to a filter with the given name.
  57
  58 af_del <filter_name_list> (comma separated list of audio filter's names)
  59     (experimental) Unload the first occurrence of the filters, if loaded.
  60
  61 af_switch <filter_arguments_list> (comma separated list of audio filters with parameters)
  62     (experimental) Remove all the audio filters and replace them with the given list.
  63
  64 alt_src_step <value> (ASX playlist only)
  65     When more than one source is available it selects the next/previous one.
  66
  67 audio_delay <value> [abs]
  68     Set/adjust the audio delay.
  69     If [abs] is not given or is zero, adjust the delay by <value> seconds.
  70     If [abs] is nonzero, set the delay to <value> seconds.
  71
  72 [brightness|contrast|gamma|hue|saturation] <value> [abs]
  73     Set/adjust video parameters.
  74     If [abs] is not given or is zero, modifies parameter by <value>.
  75     If [abs] is non-zero, parameter is set to <value>.
  76     <value> is in the range [-100, 100].
  77
  78 capturing [value]
  79     Toggle/set capturing the primary stream like -dumpstream.
  80     Requires the -capture parameter to be given.
  81
  82 change_rectangle <val1> <val2>
  83     Change the position of the rectangle filter rectangle.
  84         <val1>
  85             Must be one of the following:
  86                 0 = width
  87                 1 = height
  88                 2 = x position
  89                 3 = y position
  90         <val2>
  91             If <val1> is 0 or 1:
  92                 Integer amount to add/subtract from the width/height.
  93                 Positive values add to width/height and negative values
  94                 subtract from it.
  95             If <val1> is 2 or 3:
  96                 Relative integer amount by which to move the upper left
  97                 rectangle corner. Positive values move the rectangle
  98                 right/down and negative values move the rectangle left/up.
  99
 100 dvb_set_channel <channel_number> <card_number>
 101     Set DVB channel.
 102
 103 dvdnav <button_name>
 104     Press the given dvdnav button.
 105         up
 106         down
 107         left
 108         right
 109         menu
 110         select
 111         prev
 112         mouse
 113
 114 edl_mark
 115     Write the current position into the EDL file.
 116
 117 frame_drop [value]
 118     Toggle/set frame dropping mode.
 119
 120 get_audio_bitrate
 121     Print out the audio bitrate of the current file.
 122
 123 get_audio_codec
 124     Print out the audio codec name of the current file.
 125
 126 get_audio_samples
 127     Print out the audio frequency and number of channels of the current file.
 128
 129 get_file_name
 130     Print out the name of the current file.
 131
 132 get_meta_album
 133     Print out the 'Album' metadata of the current file.
 134
 135 get_meta_artist
 136     Print out the 'Artist' metadata of the current file.
 137
 138 get_meta_comment
 139     Print out the 'Comment' metadata of the current file.
 140
 141 get_meta_genre
 142     Print out the 'Genre' metadata of the current file.
 143
 144 get_meta_title
 145     Print out the 'Title' metadata of the current file.
 146
 147 get_meta_track
 148     Print out the 'Track Number' metadata of the current file.
 149
 150 get_meta_year
 151     Print out the 'Year' metadata of the current file.
 152
 153 get_percent_pos
 154     Print out the current position in the file, as integer percentage [0-100).
 155
 156 get_property <property>
 157     Print out the current value of a property.
 158
 159 get_sub_visibility
 160     Print out subtitle visibility (1 == on, 0 == off).
 161
 162 get_time_length
 163     Print out the length of the current file in seconds.
 164
 165 get_time_pos
 166     Print out the current position in the file in seconds, as float.
 167
 168 get_vo_fullscreen
 169     Print out fullscreen status (1 == fullscreened, 0 == windowed).
 170
 171 get_video_bitrate
 172     Print out the video bitrate of the current file.
 173
 174 get_video_codec
 175     Print out the video codec name of the current file.
 176
 177 get_video_resolution
 178     Print out the video resolution of the current file.
 179
 180 screenshot <each_frame> <full_window>
 181     Take a screenshot. Requires the screenshot filter to be loaded.
 182     each_frame:
 183         0 Take a single screenshot. (Default.)
 184         1 Start/stop taking screenshot of each frame.
 185     full_window:
 186         0 Save the video image, in its original resolution. Typically without
 187           OSD or subtitles. (Default.)
 188         1 Save the contents of the mplayer window. Typically with OSD and
 189           subtitles. If not available (no VO support), this may act as if 0 was
 190           passed.
 191
 192 key_down_event <value>
 193     Inject <value> key code event into MPlayer.
 194
 195 loadfile <file|url> <append>
 196     Load the given file/URL, stopping playback of the current file/URL.
 197     If <append> is nonzero playback continues and the file/URL is
 198     appended to the current playlist instead.
 199
 200 loadlist <file> <append>
 201     Load the given playlist file, stopping playback of the current file.
 202     If <append> is nonzero playback continues and the playlist file is
 203     appended to the current playlist instead.
 204
 205 loop <value> [abs]
 206     Adjust/set how many times the movie should be looped. -1 means no loop,
 207     and 0 forever.
 208
 209 mute [value]
 210     Toggle sound output muting or set it to [value] when [value] >= 0
 211     (1 == on, 0 == off).
 212
 213 osd [level]
 214     Toggle OSD mode or set it to [level] when [level] >= 0.
 215
 216 osd_show_progression
 217     Show the progression bar, the elapsed time and the total duration of the
 218     movie on the OSD.
 219
 220 osd_show_property_text <string> [duration] [level]
 221     Show an expanded property string on the OSD, see -playing-msg for a
 222     description of the available expansions. If [duration] is >= 0 the text
 223     is shown for [duration] ms. [level] sets the minimum OSD level needed
 224     for the message to be visible (default: 0 - always show).
 225
 226 osd_show_text <string> [duration] [level]
 227     Show <string> on the OSD.
 228
 229 panscan <-1.0 - 1.0> | <0.0 - 1.0> <abs>
 230     Increase or decrease the pan-and-scan range by <value>, 1.0 is the maximum.
 231     Negative values decrease the pan-and-scan range.
 232     If <abs> is != 0, then the pan-and scan range is interpreted as an
 233     absolute range.
 234
 235 pause
 236     Pause/unpause the playback (use "set_property pause X" to set a particular
 237     value regardless of whether the player is already paused or not).
 238
 239 frame_step
 240     Play one frame, then pause again.
 241
 242 pt_step <value> [force]
 243     Go to the next/previous entry in the playtree. The sign of <value> tells
 244     the direction.  If no entry is available in the given direction it will do
 245     nothing unless [force] is non-zero.
 246
 247 pt_up_step <value> [force]
 248     Similar to pt_step but jumps to the next/previous entry in the parent list.
 249     Useful to break out of the inner loop in the playtree.
 250
 251 quit [value]
 252     Quit MPlayer. The optional integer [value] is used as the return code
 253     for the mplayer process (default: 0).
 254
 255 radio_set_channel <channel>
 256     Switch to <channel>. The 'channels' radio parameter needs to be set.
 257
 258 radio_set_freq <frequency in MHz>
 259     Set the radio tuner frequency.
 260
 261 radio_step_channel <-1|1>
 262     Step forwards (1) or backwards (-1) in channel list. Works only when the
 263     'channels' radio parameter was set.
 264
 265 radio_step_freq <value>
 266     Tune frequency by the <value> (positive - up, negative - down).
 267
 268 run <value>
 269     Run <value> as shell command.
 270
 271 seek <value> [type] [hr-seek]
 272     Seek to some place in the movie.
 273         type = 0 is a relative seek of +/- <value> seconds (default).
 274         type = 1 is a seek to <value> % in the movie.
 275         type = 2 is a seek to an absolute position of <value> seconds.
 276     The hr-seek parameter controls whether to use precise seeks (not limited
 277     to keyframe positions in video).
 278         hr-seek = 0 means use default set with option -hr-seek (default).
 279         hr-seek = 1 means force precise seek if possible.
 280         hr-seek = -1 means force non-precise seek.
 281
 282 seek_chapter <value> [type]
 283     Seek to the start of a chapter.
 284         0 is a relative seek of +/- <value> chapters (default).
 285         1 is a seek to chapter <value>.
 286
 287 switch_angle <value>
 288     Switch to the angle with the ID [value]. Cycle through the
 289     available angles if [value] is omitted or negative.
 290
 291 set_mouse_pos <x> <y>
 292     Tells MPlayer the coordinates of the mouse in the window.
 293     This command doesn't move the mouse!
 294
 295 set_property <property> <value>
 296     Set a property.
 297
 298 set_property_osd <property> <value>
 299     Same as above, but show the new value on the OSD in the standard
 300     manner defined for that property (if any).
 301
 302 speed_incr <value>
 303     Add <value> to the current playback speed.
 304
 305 speed_mult <value>
 306     Multiply the current speed by <value>.
 307
 308 speed_set <value>
 309     Set the speed to <value>.
 310
 311 step_property <property> [value] [direction]
 312     Change a property by value, or increase by a default if value is
 313     not given or zero. The direction is reversed if direction is less
 314     than zero.
 315
 316 step_property_osd <property> [value] [direction]
 317     Same as above, but show the new value on the OSD in the standard
 318     manner defined for that property (if any).
 319
 320 stop
 321     Stop playback.
 322
 323 sub_alignment [value]
 324     Toggle/set subtitle alignment.
 325         0 top alignment
 326         1 center alignment
 327         2 bottom alignment
 328
 329 sub_delay <value> [abs]
 330     Adjust the subtitle delay by +/- <value> seconds or set it to <value>
 331     seconds when [abs] is nonzero.
 332
 333 sub_load <subtitle_file>
 334     Loads subtitles from <subtitle_file>.
 335
 336 sub_log
 337     Logs the current or last displayed subtitle together with filename
 338     and time information to ~/.mplayer/subtitle_log. Intended purpose
 339     is to allow convenient marking of bogus subtitles which need to be
 340     fixed while watching the movie.
 341
 342 sub_pos <value> [abs]
 343     Adjust/set subtitle position.
 344
 345 sub_remove [value]
 346     If the [value] argument is present and non-negative, removes the subtitle
 347     file with index [value]. If the argument is omitted or negative, removes
 348     all subtitle files.
 349
 350 sub_select [value]
 351     Display subtitle with index [value]. Turn subtitle display off if
 352     [value] is -1 or greater than the highest available subtitle index.
 353     Cycle through the available subtitles if [value] is omitted or less
 354     than -1 (forward or backward respectively).
 355     Supported subtitle sources are -sub options on the command
 356     line, VOBsubs, DVD subtitles, and Ogg and Matroska text streams.
 357     This command is mainly for cycling all subtitles, if you want to set
 358     a specific subtitle, use sub_file, sub_vob, or sub_demux.
 359
 360 sub_source [source]
 361     Display first subtitle from [source]. Here [source] is an integer:
 362     SUB_SOURCE_SUBS   (0) for file subs
 363     SUB_SOURCE_VOBSUB (1) for VOBsub files
 364     SUB_SOURCE_DEMUX  (2) for subtitle embedded in the media file or DVD subs.
 365     If [source] is -1, will turn off subtitle display.
 366     If [value] is omitted or less than -1, will cycle between the first subtitle
 367     of each currently available source (forward or backward respectively).
 368
 369 sub_file [value]
 370     Display subtitle specifid by [value] for file subs. The [value] is
 371     corresponding to ID_FILE_SUB_ID values reported by '-identify'.
 372     If [value] is -1, will turn off subtitle display.
 373     If [value] is omitted or less than -1, will cycle all file subs
 374     (forward or backward respectively).
 375
 376 sub_vob [value]
 377     Display subtitle specifid by [value] for vobsubs. The [value] is
 378     corresponding to ID_VOBSUB_ID values reported by '-identify'.
 379     If [value] is -1, will turn off subtitle display.
 380     If [value] is omitted or less than -1, will cycle all vobsubs
 381     (forward or backward respectively).
 382
 383 sub_demux [value]
 384     Display subtitle specifid by [value] for subtitles from DVD or embedded
 385     in media file. The [value] is corresponding to ID_SUBTITLE_ID values
 386     reported by '-identify'. If [value] is -1, will turn off subtitle display.
 387     If [value] is omitted or less than -1, will cycle all DVD subs or embedded subs
 388     (forward or backward respectively).
 389
 390 sub_scale <value> [abs]
 391     Adjust the subtitle size by +/- <value> or set it to <value> when [abs]
 392     is nonzero.
 393
 394 vobsub_lang
 395     This is a stub linked to sub_select for backwards compatibility.
 396
 397 sub_step <value>
 398     Step forward in the subtitle list by <value> steps or backwards if <value>
 399     is negative.
 400
 401 sub_visibility [value]
 402     Toggle/set subtitle visibility.
 403
 404 forced_subs_only [value]
 405     Toggle/set forced subtitles only.
 406
 407 switch_audio [value] (currently MPEG*, AVI, Matroska and streams handled by libavformat)
 408     Switch to the audio track with the ID [value]. Cycle through the
 409     available tracks if [value] is omitted or negative.
 410
 411 switch_angle [value] (DVDs only)
 412     Switch to the DVD angle with the ID [value]. Cycle through the
 413     available angles if [value] is omitted or negative.
 414
 415 switch_ratio [value]
 416     Change aspect ratio at runtime. [value] is the new aspect ratio expressed
 417     as a float (e.g. 1.77778 for 16/9).
 418     There might be problems with some video filters.
 419
 420 switch_title [value] (DVDNAV only)
 421     Switch to the DVD title with the ID [value]. Cycle through the
 422     available titles if [value] is omitted or negative.
 423
 424 switch_vsync [value]
 425     Toggle vsync (1 == on, 0 == off). If [value] is not provided,
 426     vsync status is inverted.
 427
 428 teletext_add_digit <value>
 429     Enter/leave teletext page number editing mode and append given digit to
 430     previously entered one.
 431     0..9 - Append apropriate digit. (Enables editing mode if called from normal
 432            mode, and switches to normal mode when third digit is entered.)
 433     -    - Delete last digit from page number. (Backspace emulation, works only
 434            in page number editing mode.)
 435
 436 teletext_go_link <1-6>
 437     Follow given link on current teletext page.
 438
 439 tv_start_scan
 440     Start automatic TV channel scanning.
 441
 442 tv_step_channel <channel>
 443     Select next/previous TV channel.
 444
 445 tv_step_norm
 446     Change TV norm.
 447
 448 tv_step_chanlist
 449     Change channel list.
 450
 451 tv_set_channel <channel>
 452     Set the current TV channel.
 453
 454 tv_last_channel
 455     Set the current TV channel to the last one.
 456
 457 tv_set_freq <frequency in MHz>
 458     Set the TV tuner frequency.
 459
 460 tv_step_freq <frequency offset in MHz>
 461     Set the TV tuner frequency relative to current value.
 462
 463 tv_set_norm <norm>
 464     Set the TV tuner norm (PAL, SECAM, NTSC, ...).
 465
 466 tv_set_brightness <-100 - 100> [abs]
 467     Set TV tuner brightness or adjust it if [abs] is set to 0.
 468
 469 tv_set_contrast <-100 -100> [abs]
 470     Set TV tuner contrast or adjust it if [abs] is set to 0.
 471
 472 tv_set_hue <-100 - 100> [abs]
 473     Set TV tuner hue or adjust it if [abs] is set to 0.
 474
 475 tv_set_saturation <-100 - 100> [abs]
 476     Set TV tuner saturation or adjust it if [abs] is set to 0.
 477
 478 use_master
 479     Switch volume control between master and PCM.
 480
 481 vo_border [value]
 482     Toggle/set borderless display.
 483
 484 vo_fullscreen [value]
 485     Toggle/set fullscreen mode.
 486
 487 vo_ontop [value]
 488     Toggle/set stay-on-top.
 489
 490 vo_rootwin [value]
 491     Toggle/set playback on the root window.
 492
 493 volume <value> [abs]
 494     Increase/decrease volume or set it to <value> if [abs] is nonzero.
 495
 496
 497 Available properties:
 498
 499 name               type      min     max     get set step comment
 500 =================================================================
 501
 502 osdlevel           int       0       3       X   X   X    as -osdlevel
 503 speed              float     0.01    100     X   X   X    as -speed
 504 loop               int       -1              X   X   X    as -loop
 505 hr_seek            string                    X   X   X    as -hr-seek
 506 pts_association_mode string                  X   X   X    as -pts-association-mode
 507 pause              flag      0       1       X            1 if paused
 508 filename           string                    X            file playing wo path
 509 path               string                    X            file playing
 510 demuxer            string                    X            demuxer used
 511 stream_pos         pos       0               X   X        position in stream
 512 stream_start       pos       0               X            start pos in stream
 513 stream_end         pos       0               X            end pos in stream
 514 stream_length      pos       0               X            (end - start)
 515 stream_time_pos    time      0               X            present position in stream (in seconds)
 516 chapter            int       0               X   X   X    select chapter
 517 chapters           int                       X            number of chapters
 518 angle              int       0               X   X   X    select angle
 519 length             time                      X            length of file in seconds
 520 percent_pos        int       0       100     X   X   X    position in percent
 521 time_pos           time      0               X   X   X    position in seconds
 522 metadata           str list                  X            list of metadata key/value
 523 metadata/*         string                    X            metadata values
 524 volume             float     0       100     X   X   X    change volume
 525 balance            float     -1      1       X   X   X    change audio balance
 526 mute               flag      0       1       X   X   X
 527 audio_delay        float     -100    100     X   X   X
 528 audio_format       int                       X
 529 audio_codec        string                    X
 530 audio_bitrate      int                       X
 531 samplerate         int                       X
 532 channels           int                       X
 533 switch_audio       int       -2      255     X   X   X    select audio stream
 534 switch_angle       int       -2      255     X   X   X    select DVD angle
 535 switch_title       int       -2      255     X   X   X    select DVD title
 536 capturing          flag      0       1       X   X   X    dump primary stream if enabled
 537 fullscreen         flag      0       1       X   X   X
 538 deinterlace        flag      0       1       X   X   X
 539 ontop              flag      0       1       X   X   X
 540 rootwin            flag      0       1       X   X   X
 541 border             flag      0       1       X   X   X
 542 framedropping      int       0       2       X   X   X    1 = soft, 2 = hard
 543 gamma              int       -100    100     X   X   X
 544 brightness         int       -100    100     X   X   X
 545 contrast           int       -100    100     X   X   X
 546 saturation         int       -100    100     X   X   X
 547 hue                int       -100    100     X   X   X
 548 panscan            float     0       1       X   X   X
 549 vsync              flag      0       1       X   X   X
 550 colormatrix        choice                    X   X   X    as --colormatrix
 551 colormatrix_input_range choice               X   X   X    as --colormatrix-input-range
 552 colormatrix_output_range choice              X   X   X    as --colormatrix-output-range
 553 video_format       int                       X
 554 video_codec        string                    X
 555 video_bitrate      int                       X
 556 width              int                       X            "display" width
 557 height             int                       X            "display" height
 558 fps                float                     X
 559 aspect             float                     X
 560 switch_video       int       -2      255     X   X   X    select video stream
 561 switch_program     int       -1      65535   X   X   X    (see TAB default keybind)
 562 sub                int       -1              X   X   X    select subtitle stream
 563 sub_source         int       -1      2       X   X   X    select subtitle source
 564 sub_file           int       -1              X   X   X    select file subtitles
 565 sub_vob            int       -1              X   X   X    select vobsubs
 566 sub_demux          int       -1              X   X   X    select subs from demux
 567 sub_delay          float                     X   X   X
 568 sub_pos            int       0       100     X   X   X    subtitle position
 569 sub_alignment      int       0       2       X   X   X    subtitle alignment
 570 sub_visibility     flag      0       1       X   X   X    show/hide subtitles
 571 sub_forced_only    flag      0       1       X   X   X
 572 sub_scale          float     0       100     X   X   X    subtitles font size
 573 ass_vsfilter_aspect_compat flag 0    1       X   X   X    SSA/ASS aspect ratio correction
 574 tv_brightness      int       -100    100     X   X   X
 575 tv_contrast        int       -100    100     X   X   X
 576 tv_saturation      int       -100    100     X   X   X
 577 tv_hue             int       -100    100     X   X   X
 578 teletext_page      int       0       799     X   X   X
 579 teletext_subpage   int       0       64      X   X   X
 580 teletext_mode      flag      0       1       X   X   X    0 - off, 1 - on
 581 teletext_format    int       0       3       X   X   X    0 - opaque,
 582                                                           1 - transparent,
 583                                                           2 - opaque inverted,
 584                                                           3 - transp. inv.
 585 teletext_half_page int       0       2       X   X   X    0 - off, 1 - top half,
 586                                                           2- bottom half