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]
 312     Change a property by value, or increase by a default if value is
 313     not given.
 314
 315 step_property_osd <property> [value]
 316     Same as above, but show the new value on the OSD in the standard
 317     manner defined for that property (if any).
 318
 319 stop
 320     Stop playback.
 321
 322 sub_alignment [value]
 323     Toggle/set subtitle alignment.
 324         0 top alignment
 325         1 center alignment
 326         2 bottom alignment
 327
 328 sub_delay <value> [abs]
 329     Adjust the subtitle delay by +/- <value> seconds or set it to <value>
 330     seconds when [abs] is nonzero.
 331
 332 sub_load <subtitle_file>
 333     Loads subtitles from <subtitle_file>.
 334
 335 sub_log
 336     Logs the current or last displayed subtitle together with filename
 337     and time information to ~/.mplayer/subtitle_log. Intended purpose
 338     is to allow convenient marking of bogus subtitles which need to be
 339     fixed while watching the movie.
 340
 341 sub_pos <value> [abs]
 342     Adjust/set subtitle position.
 343
 344 sub_remove [value]
 345     If the [value] argument is present and non-negative, removes the subtitle
 346     file with index [value]. If the argument is omitted or negative, removes
 347     all subtitle files.
 348
 349 sub_select [value]
 350     Display subtitle with index [value]. Turn subtitle display off if
 351     [value] is -1 or greater than the highest available subtitle index.
 352     Cycle through the available subtitles if [value] is omitted or less
 353     than -1 (forward or backward respectively).
 354     Supported subtitle sources are -sub options on the command
 355     line, VOBsubs, DVD subtitles, and Ogg and Matroska text streams.
 356     This command is mainly for cycling all subtitles, if you want to set
 357     a specific subtitle, use sub_file, sub_vob, or sub_demux.
 358
 359 sub_source [source]
 360     Display first subtitle from [source]. Here [source] is an integer:
 361     SUB_SOURCE_SUBS   (0) for file subs
 362     SUB_SOURCE_VOBSUB (1) for VOBsub files
 363     SUB_SOURCE_DEMUX  (2) for subtitle embedded in the media file or DVD subs.
 364     If [source] is -1, will turn off subtitle display.
 365     If [value] is omitted or less than -1, will cycle between the first subtitle
 366     of each currently available source (forward or backward respectively).
 367
 368 sub_file [value]
 369     Display subtitle specifid by [value] for file subs. The [value] is
 370     corresponding to ID_FILE_SUB_ID values reported by '-identify'.
 371     If [value] is -1, will turn off subtitle display.
 372     If [value] is omitted or less than -1, will cycle all file subs
 373     (forward or backward respectively).
 374
 375 sub_vob [value]
 376     Display subtitle specifid by [value] for vobsubs. The [value] is
 377     corresponding to ID_VOBSUB_ID values reported by '-identify'.
 378     If [value] is -1, will turn off subtitle display.
 379     If [value] is omitted or less than -1, will cycle all vobsubs
 380     (forward or backward respectively).
 381
 382 sub_demux [value]
 383     Display subtitle specifid by [value] for subtitles from DVD or embedded
 384     in media file. The [value] is corresponding to ID_SUBTITLE_ID values
 385     reported by '-identify'. If [value] is -1, will turn off subtitle display.
 386     If [value] is omitted or less than -1, will cycle all DVD subs or embedded subs
 387     (forward or backward respectively).
 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 Available properties:
 497
 498 name               type      min     max     get set step comment
 499 =================================================================
 500
 501 osdlevel           int       0       3       X   X   X    as -osdlevel
 502 speed              float     0.01    100     X   X   X    as -speed
 503 loop               int       -1              X   X   X    as -loop
 504 hr_seek            string                    X   X   X    as -hr-seek
 505 pts_association_mode string                  X   X   X    as -pts-association-mode
 506 pause              flag      0       1       X            1 if paused
 507 filename           string                    X            file playing wo path
 508 path               string                    X            file playing
 509 demuxer            string                    X            demuxer used
 510 stream_pos         pos       0               X   X        position in stream
 511 stream_start       pos       0               X            start pos in stream
 512 stream_end         pos       0               X            end pos in stream
 513 stream_length      pos       0               X            (end - start)
 514 stream_time_pos    time      0               X            present position in stream (in seconds)
 515 chapter            int       0               X   X   X    select chapter
 516 chapters           int                       X            number of chapters
 517 angle              int       0               X   X   X    select angle
 518 length             time                      X            length of file in seconds
 519 percent_pos        int       0       100     X   X   X    position in percent
 520 time_pos           time      0               X   X   X    position in seconds
 521 metadata           str list                  X            list of metadata key/value
 522 metadata/*         string                    X            metadata values
 523 volume             float     0       100     X   X   X    change volume
 524 balance            float     -1      1       X   X   X    change audio balance
 525 mute               flag      0       1       X   X   X
 526 audio_delay        float     -100    100     X   X   X
 527 audio_format       int                       X
 528 audio_codec        string                    X
 529 audio_bitrate      int                       X
 530 samplerate         int                       X
 531 channels           int                       X
 532 switch_audio       int       -2      255     X   X   X    select audio stream
 533 switch_angle       int       -2      255     X   X   X    select DVD angle
 534 switch_title       int       -2      255     X   X   X    select DVD title
 535 capturing          flag      0       1       X   X   X    dump primary stream if enabled
 536 fullscreen         flag      0       1       X   X   X
 537 deinterlace        flag      0       1       X   X   X
 538 ontop              flag      0       1       X   X   X
 539 rootwin            flag      0       1       X   X   X
 540 border             flag      0       1       X   X   X
 541 framedropping      int       0       2       X   X   X    1 = soft, 2 = hard
 542 gamma              int       -100    100     X   X   X
 543 brightness         int       -100    100     X   X   X
 544 contrast           int       -100    100     X   X   X
 545 saturation         int       -100    100     X   X   X
 546 hue                int       -100    100     X   X   X
 547 panscan            float     0       1       X   X   X
 548 vsync              flag      0       1       X   X   X
 549 colormatrix        choice                    X   X   X    as --colormatrix
 550 colormatrix_input_range choice               X   X   X    as --colormatrix-input-range
 551 colormatrix_output_range choice              X   X   X    as --colormatrix-output-range
 552 video_format       int                       X
 553 video_codec        string                    X
 554 video_bitrate      int                       X
 555 width              int                       X            "display" width
 556 height             int                       X            "display" height
 557 fps                float                     X
 558 aspect             float                     X
 559 switch_video       int       -2      255     X   X   X    select video stream
 560 switch_program     int       -1      65535   X   X   X    (see TAB default keybind)
 561 sub                int       -1              X   X   X    select subtitle stream
 562 sub_source         int       -1      2       X   X   X    select subtitle source
 563 sub_file           int       -1              X   X   X    select file subtitles
 564 sub_vob            int       -1              X   X   X    select vobsubs
 565 sub_demux          int       -1              X   X   X    select subs from demux
 566 sub_delay          float                     X   X   X
 567 sub_pos            int       0       100     X   X   X    subtitle position
 568 sub_alignment      int       0       2       X   X   X    subtitle alignment
 569 sub_visibility     flag      0       1       X   X   X    show/hide subtitles
 570 sub_forced_only    flag      0       1       X   X   X
 571 sub_scale          float     0       100     X   X   X    subtitles font size
 572 ass_vsfilter_aspect_compat flag 0    1       X   X   X    SSA/ASS aspect ratio correction
 573 tv_brightness      int       -100    100     X   X   X
 574 tv_contrast        int       -100    100     X   X   X
 575 tv_saturation      int       -100    100     X   X   X
 576 tv_hue             int       -100    100     X   X   X
 577 teletext_page      int       0       799     X   X   X
 578 teletext_subpage   int       0       64      X   X   X
 579 teletext_mode      flag      0       1       X   X   X    0 - off, 1 - on
 580 teletext_format    int       0       3       X   X   X    0 - opaque,
 581                                                           1 - transparent,
 582                                                           2 - opaque inverted,
 583                                                           3 - transp. inv.
 584 teletext_half_page int       0       2       X   X   X    0 - off, 1 - top half,
 585                                                           2- bottom half