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