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 <value>
 181     Take a screenshot. Requires the screenshot filter to be loaded.
 182         0 Take a single screenshot.
 183         1 Start/stop taking screenshot of each frame.
 184
 185 key_down_event <value>
 186     Inject <value> key code event into MPlayer.
 187
 188 loadfile <file|url> <append>
 189     Load the given file/URL, stopping playback of the current file/URL.
 190     If <append> is nonzero playback continues and the file/URL is
 191     appended to the current playlist instead.
 192
 193 loadlist <file> <append>
 194     Load the given playlist file, stopping playback of the current file.
 195     If <append> is nonzero playback continues and the playlist file is
 196     appended to the current playlist instead.
 197
 198 loop <value> [abs]
 199     Adjust/set how many times the movie should be looped. -1 means no loop,
 200     and 0 forever.
 201
 202 menu <command>
 203     Execute an OSD menu command.
 204         up     Move cursor up.
 205         down   Move cursor down.
 206         ok     Accept selection.
 207         cancel Cancel selection.
 208         hide   Hide the OSD menu.
 209
 210 set_menu <menu_name>
 211     Display the menu named <menu_name>.
 212
 213 mute [value]
 214     Toggle sound output muting or set it to [value] when [value] >= 0
 215     (1 == on, 0 == off).
 216
 217 osd [level]
 218     Toggle OSD mode or set it to [level] when [level] >= 0.
 219
 220 osd_show_progression
 221     Show the progression bar, the elapsed time and the total duration of the
 222     movie on the OSD.
 223
 224 osd_show_property_text <string> [duration] [level]
 225     Show an expanded property string on the OSD, see -playing-msg for a
 226     description of the available expansions. If [duration] is >= 0 the text
 227     is shown for [duration] ms. [level] sets the minimum OSD level needed
 228     for the message to be visible (default: 0 - always show).
 229
 230 osd_show_text <string> [duration] [level]
 231     Show <string> on the OSD.
 232
 233 panscan <-1.0 - 1.0> | <0.0 - 1.0> <abs>
 234     Increase or decrease the pan-and-scan range by <value>, 1.0 is the maximum.
 235     Negative values decrease the pan-and-scan range.
 236     If <abs> is != 0, then the pan-and scan range is interpreted as an
 237     absolute range.
 238
 239 pause
 240     Pause/unpause the playback (use "set_property pause X" to set a particular
 241     value regardless of whether the player is already paused or not).
 242
 243 frame_step
 244     Play one frame, then pause again.
 245
 246 pt_step <value> [force]
 247     Go to the next/previous entry in the playtree. The sign of <value> tells
 248     the direction.  If no entry is available in the given direction it will do
 249     nothing unless [force] is non-zero.
 250
 251 pt_up_step <value> [force]
 252     Similar to pt_step but jumps to the next/previous entry in the parent list.
 253     Useful to break out of the inner loop in the playtree.
 254
 255 quit [value]
 256     Quit MPlayer. The optional integer [value] is used as the return code
 257     for the mplayer process (default: 0).
 258
 259 radio_set_channel <channel>
 260     Switch to <channel>. The 'channels' radio parameter needs to be set.
 261
 262 radio_set_freq <frequency in MHz>
 263     Set the radio tuner frequency.
 264
 265 radio_step_channel <-1|1>
 266     Step forwards (1) or backwards (-1) in channel list. Works only when the
 267     'channels' radio parameter was set.
 268
 269 radio_step_freq <value>
 270     Tune frequency by the <value> (positive - up, negative - down).
 271
 272 seek <value> [type] [hr-seek]
 273     Seek to some place in the movie.
 274         type = 0 is a relative seek of +/- <value> seconds (default).
 275         type = 1 is a seek to <value> % in the movie.
 276         type = 2 is a seek to an absolute position of <value> seconds.
 277     The hr-seek parameter controls whether to use precise seeks (not limited
 278     to keyframe positions in video).
 279         hr-seek = 0 means use default set with option -hr-seek (default).
 280         hr-seek = 1 means force precise seek if possible.
 281         hr-seek = -1 means force non-precise seek.
 282
 283 seek_chapter <value> [type]
 284     Seek to the start of a chapter.
 285         0 is a relative seek of +/- <value> chapters (default).
 286         1 is a seek to chapter <value>.
 287
 288 switch_angle <value>
 289     Switch to the angle with the ID [value]. Cycle through the
 290     available angles if [value] is omitted or negative.
 291
 292 set_mouse_pos <x> <y>
 293     Tells MPlayer the coordinates of the mouse in the window.
 294     This command doesn't move the mouse!
 295
 296 set_property <property> <value>
 297     Set a property.
 298
 299 set_property_osd <property> <value>
 300     Same as above, but show the new value on the OSD in the standard
 301     manner defined for that property (if any).
 302
 303 speed_incr <value>
 304     Add <value> to the current playback speed.
 305
 306 speed_mult <value>
 307     Multiply the current speed by <value>.
 308
 309 speed_set <value>
 310     Set the speed to <value>.
 311
 312 step_property <property> [value] [direction]
 313     Change a property by value, or increase by a default if value is
 314     not given or zero. The direction is reversed if direction is less
 315     than zero.
 316
 317 step_property_osd <property> [value] [direction]
 318     Same as above, but show the new value on the OSD in the standard
 319     manner defined for that property (if any).
 320
 321 stop
 322     Stop playback.
 323
 324 sub_alignment [value]
 325     Toggle/set subtitle alignment.
 326         0 top alignment
 327         1 center alignment
 328         2 bottom alignment
 329
 330 sub_delay <value> [abs]
 331     Adjust the subtitle delay by +/- <value> seconds or set it to <value>
 332     seconds when [abs] is nonzero.
 333
 334 sub_load <subtitle_file>
 335     Loads subtitles from <subtitle_file>.
 336
 337 sub_log
 338     Logs the current or last displayed subtitle together with filename
 339     and time information to ~/.mplayer/subtitle_log. Intended purpose
 340     is to allow convenient marking of bogus subtitles which need to be
 341     fixed while watching the movie.
 342
 343 sub_pos <value> [abs]
 344     Adjust/set subtitle position.
 345
 346 sub_remove [value]
 347     If the [value] argument is present and non-negative, removes the subtitle
 348     file with index [value]. If the argument is omitted or negative, removes
 349     all subtitle files.
 350
 351 sub_select [value]
 352     Display subtitle with index [value]. Turn subtitle display off if
 353     [value] is -1 or greater than the highest available subtitle index.
 354     Cycle through the available subtitles if [value] is omitted or less
 355     than -1 (forward or backward respectively).
 356     Supported subtitle sources are -sub options on the command
 357     line, VOBsubs, DVD subtitles, and Ogg and Matroska text streams.
 358     This command is mainly for cycling all subtitles, if you want to set
 359     a specific subtitle, use sub_file, sub_vob, or sub_demux.
 360
 361 sub_source [source]
 362     Display first subtitle from [source]. Here [source] is an integer:
 363     SUB_SOURCE_SUBS   (0) for file subs
 364     SUB_SOURCE_VOBSUB (1) for VOBsub files
 365     SUB_SOURCE_DEMUX  (2) for subtitle embedded in the media file or DVD subs.
 366     If [source] is -1, will turn off subtitle display.
 367     If [value] is omitted or less than -1, will cycle between the first subtitle
 368     of each currently available source (forward or backward respectively).
 369
 370 sub_file [value]
 371     Display subtitle specifid by [value] for file subs. The [value] is
 372     corresponding to ID_FILE_SUB_ID values reported by '-identify'.
 373     If [value] is -1, will turn off subtitle display.
 374     If [value] is omitted or less than -1, will cycle all file subs
 375     (forward or backward respectively).
 376
 377 sub_vob [value]
 378     Display subtitle specifid by [value] for vobsubs. The [value] is
 379     corresponding to ID_VOBSUB_ID values reported by '-identify'.
 380     If [value] is -1, will turn off subtitle display.
 381     If [value] is omitted or less than -1, will cycle all vobsubs
 382     (forward or backward respectively).
 383
 384 sub_demux [value]
 385     Display subtitle specifid by [value] for subtitles from DVD or embedded
 386     in media file. The [value] is corresponding to ID_SUBTITLE_ID values
 387     reported by '-identify'. If [value] is -1, will turn off subtitle display.
 388     If [value] is omitted or less than -1, will cycle all DVD subs or embedded subs
 389     (forward or backward respectively).
 390
 391 sub_scale <value> [abs]
 392     Adjust the subtitle size by +/- <value> or set it to <value> when [abs]
 393     is nonzero.
 394
 395 vobsub_lang
 396     This is a stub linked to sub_select for backwards compatibility.
 397
 398 sub_step <value>
 399     Step forward in the subtitle list by <value> steps or backwards if <value>
 400     is negative.
 401
 402 sub_visibility [value]
 403     Toggle/set subtitle visibility.
 404
 405 forced_subs_only [value]
 406     Toggle/set forced subtitles only.
 407
 408 switch_audio [value] (currently MPEG*, AVI, Matroska and streams handled by libavformat)
 409     Switch to the audio track with the ID [value]. Cycle through the
 410     available tracks if [value] is omitted or negative.
 411
 412 switch_angle [value] (DVDs only)
 413     Switch to the DVD angle with the ID [value]. Cycle through the
 414     available angles if [value] is omitted or negative.
 415
 416 switch_ratio [value]
 417     Change aspect ratio at runtime. [value] is the new aspect ratio expressed
 418     as a float (e.g. 1.77778 for 16/9).
 419     There might be problems with some video filters.
 420
 421 switch_title [value] (DVDNAV only)
 422     Switch to the DVD title with the ID [value]. Cycle through the
 423     available titles if [value] is omitted or negative.
 424
 425 switch_vsync [value]
 426     Toggle vsync (1 == on, 0 == off). If [value] is not provided,
 427     vsync status is inverted.
 428
 429 teletext_add_digit <value>
 430     Enter/leave teletext page number editing mode and append given digit to
 431     previously entered one.
 432     0..9 - Append apropriate digit. (Enables editing mode if called from normal
 433            mode, and switches to normal mode when third digit is entered.)
 434     -    - Delete last digit from page number. (Backspace emulation, works only
 435            in page number editing mode.)
 436
 437 teletext_go_link <1-6>
 438     Follow given link on current teletext page.
 439
 440 tv_start_scan
 441     Start automatic TV channel scanning.
 442
 443 tv_step_channel <channel>
 444     Select next/previous TV channel.
 445
 446 tv_step_norm
 447     Change TV norm.
 448
 449 tv_step_chanlist
 450     Change channel list.
 451
 452 tv_set_channel <channel>
 453     Set the current TV channel.
 454
 455 tv_last_channel
 456     Set the current TV channel to the last one.
 457
 458 tv_set_freq <frequency in MHz>
 459     Set the TV tuner frequency.
 460
 461 tv_step_freq <frequency offset in MHz>
 462     Set the TV tuner frequency relative to current value.
 463
 464 tv_set_norm <norm>
 465     Set the TV tuner norm (PAL, SECAM, NTSC, ...).
 466
 467 tv_set_brightness <-100 - 100> [abs]
 468     Set TV tuner brightness or adjust it if [abs] is set to 0.
 469
 470 tv_set_contrast <-100 -100> [abs]
 471     Set TV tuner contrast or adjust it if [abs] is set to 0.
 472
 473 tv_set_hue <-100 - 100> [abs]
 474     Set TV tuner hue or adjust it if [abs] is set to 0.
 475
 476 tv_set_saturation <-100 - 100> [abs]
 477     Set TV tuner saturation or adjust it if [abs] is set to 0.
 478
 479 use_master
 480     Switch volume control between master and PCM.
 481
 482 vo_border [value]
 483     Toggle/set borderless display.
 484
 485 vo_fullscreen [value]
 486     Toggle/set fullscreen mode.
 487
 488 vo_ontop [value]
 489     Toggle/set stay-on-top.
 490
 491 vo_rootwin [value]
 492     Toggle/set playback on the root window.
 493
 494 volume <value> [abs]
 495     Increase/decrease volume or set it to <value> if [abs] is nonzero.
 496
 497
 498 The following commands are really only useful for OSD menu console mode:
 499
 500 help
 501     Displays help text, currently empty.
 502
 503 exit
 504     Exits from OSD menu console. Unlike 'quit', does not quit MPlayer.
 505
 506 hide
 507     Hides the OSD menu console. Clicking a menu command unhides it. Other
 508     keybindings act as usual.
 509
 510 run <value>
 511     Run <value> as shell command. In OSD menu console mode stdout and stdin
 512     are through the video output driver.
 513
 514
 515 Available properties:
 516
 517 name               type      min     max     get set step comment
 518 =================================================================
 519
 520 osdlevel           int       0       3       X   X   X    as -osdlevel
 521 speed              float     0.01    100     X   X   X    as -speed
 522 loop               int       -1              X   X   X    as -loop
 523 hr_seek            string                    X   X   X    as -hr-seek
 524 pts_association_mode string                  X   X   X    as -pts-association-mode
 525 pause              flag      0       1       X            1 if paused
 526 filename           string                    X            file playing wo path
 527 path               string                    X            file playing
 528 demuxer            string                    X            demuxer used
 529 stream_pos         pos       0               X   X        position in stream
 530 stream_start       pos       0               X            start pos in stream
 531 stream_end         pos       0               X            end pos in stream
 532 stream_length      pos       0               X            (end - start)
 533 stream_time_pos    time      0               X            present position in stream (in seconds)
 534 chapter            int       0               X   X   X    select chapter
 535 chapters           int                       X            number of chapters
 536 angle              int       0               X   X   X    select angle
 537 length             time                      X            length of file in seconds
 538 percent_pos        int       0       100     X   X   X    position in percent
 539 time_pos           time      0               X   X   X    position in seconds
 540 metadata           str list                  X            list of metadata key/value
 541 metadata/*         string                    X            metadata values
 542 volume             float     0       100     X   X   X    change volume
 543 balance            float     -1      1       X   X   X    change audio balance
 544 mute               flag      0       1       X   X   X
 545 audio_delay        float     -100    100     X   X   X
 546 audio_format       int                       X
 547 audio_codec        string                    X
 548 audio_bitrate      int                       X
 549 samplerate         int                       X
 550 channels           int                       X
 551 switch_audio       int       -2      255     X   X   X    select audio stream
 552 switch_angle       int       -2      255     X   X   X    select DVD angle
 553 switch_title       int       -2      255     X   X   X    select DVD title
 554 capturing          flag      0       1       X   X   X    dump primary stream if enabled
 555 fullscreen         flag      0       1       X   X   X
 556 deinterlace        flag      0       1       X   X   X
 557 ontop              flag      0       1       X   X   X
 558 rootwin            flag      0       1       X   X   X
 559 border             flag      0       1       X   X   X
 560 framedropping      int       0       2       X   X   X    1 = soft, 2 = hard
 561 gamma              int       -100    100     X   X   X
 562 brightness         int       -100    100     X   X   X
 563 contrast           int       -100    100     X   X   X
 564 saturation         int       -100    100     X   X   X
 565 hue                int       -100    100     X   X   X
 566 panscan            float     0       1       X   X   X
 567 vsync              flag      0       1       X   X   X
 568 video_format       int                       X
 569 video_codec        string                    X
 570 video_bitrate      int                       X
 571 width              int                       X            "display" width
 572 height             int                       X            "display" height
 573 fps                float                     X
 574 aspect             float                     X
 575 switch_video       int       -2      255     X   X   X    select video stream
 576 switch_program     int       -1      65535   X   X   X    (see TAB default keybind)
 577 sub                int       -1              X   X   X    select subtitle stream
 578 sub_source         int       -1      2       X   X   X    select subtitle source
 579 sub_file           int       -1              X   X   X    select file subtitles
 580 sub_vob            int       -1              X   X   X    select vobsubs
 581 sub_demux          int       -1              X   X   X    select subs from demux
 582 sub_delay          float                     X   X   X
 583 sub_pos            int       0       100     X   X   X    subtitle position
 584 sub_alignment      int       0       2       X   X   X    subtitle alignment
 585 sub_visibility     flag      0       1       X   X   X    show/hide subtitles
 586 sub_forced_only    flag      0       1       X   X   X
 587 sub_scale          float     0       100     X   X   X    subtitles font size
 588 tv_brightness      int       -100    100     X   X   X
 589 tv_contrast        int       -100    100     X   X   X
 590 tv_saturation      int       -100    100     X   X   X
 591 tv_hue             int       -100    100     X   X   X
 592 teletext_page      int       0       799     X   X   X
 593 teletext_subpage   int       0       64      X   X   X
 594 teletext_mode      flag      0       1       X   X   X    0 - off, 1 - on
 595 teletext_format    int       0       3       X   X   X    0 - opaque,
 596                                                           1 - transparent,
 597                                                           2 - opaque inverted,
 598                                                           3 - transp. inv.
 599 teletext_half_page int       0       2       X   X   X    0 - off, 1 - top half,
 600                                                           2- bottom half