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 specified 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 specified 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 specified 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_visibility [value]
 397     Toggle/set subtitle visibility.
 398
 399 forced_subs_only [value]
 400     Toggle/set forced subtitles only.
 401
 402 switch_audio [value] (currently MPEG*, AVI, Matroska and streams handled by libavformat)
 403     Switch to the audio track with the ID [value]. Cycle through the
 404     available tracks if [value] is omitted or negative.
 405
 406 switch_angle [value] (DVDs only)
 407     Switch to the DVD angle with the ID [value]. Cycle through the
 408     available angles if [value] is omitted or negative.
 409
 410 switch_ratio [value]
 411     Change aspect ratio at runtime. [value] is the new aspect ratio expressed
 412     as a float (e.g. 1.77778 for 16/9).
 413     There might be problems with some video filters.
 414
 415 switch_title [value] (DVDNAV only)
 416     Switch to the DVD title with the ID [value]. Cycle through the
 417     available titles if [value] is omitted or negative.
 418
 419 switch_vsync [value]
 420     Toggle vsync (1 == on, 0 == off). If [value] is not provided,
 421     vsync status is inverted.
 422
 423 teletext_add_digit <value>
 424     Enter/leave teletext page number editing mode and append given digit to
 425     previously entered one.
 426     0..9 - Append appropriate digit. (Enables editing mode if called from normal
 427            mode, and switches to normal mode when third digit is entered.)
 428     -    - Delete last digit from page number. (Backspace emulation, works only
 429            in page number editing mode.)
 430
 431 teletext_go_link <1-6>
 432     Follow given link on current teletext page.
 433
 434 tv_start_scan
 435     Start automatic TV channel scanning.
 436
 437 tv_step_channel <channel>
 438     Select next/previous TV channel.
 439
 440 tv_step_norm
 441     Change TV norm.
 442
 443 tv_step_chanlist
 444     Change channel list.
 445
 446 tv_set_channel <channel>
 447     Set the current TV channel.
 448
 449 tv_last_channel
 450     Set the current TV channel to the last one.
 451
 452 tv_set_freq <frequency in MHz>
 453     Set the TV tuner frequency.
 454
 455 tv_step_freq <frequency offset in MHz>
 456     Set the TV tuner frequency relative to current value.
 457
 458 tv_set_norm <norm>
 459     Set the TV tuner norm (PAL, SECAM, NTSC, ...).
 460
 461 tv_set_brightness <-100 - 100> [abs]
 462     Set TV tuner brightness or adjust it if [abs] is set to 0.
 463
 464 tv_set_contrast <-100 -100> [abs]
 465     Set TV tuner contrast or adjust it if [abs] is set to 0.
 466
 467 tv_set_hue <-100 - 100> [abs]
 468     Set TV tuner hue or adjust it if [abs] is set to 0.
 469
 470 tv_set_saturation <-100 - 100> [abs]
 471     Set TV tuner saturation or adjust it if [abs] is set to 0.
 472
 473 vo_border [value]
 474     Toggle/set borderless display.
 475
 476 vo_fullscreen [value]
 477     Toggle/set fullscreen mode.
 478
 479 vo_ontop [value]
 480     Toggle/set stay-on-top.
 481
 482 vo_rootwin [value]
 483     Toggle/set playback on the root window.
 484
 485 volume <value> [abs]
 486     Increase/decrease volume or set it to <value> if [abs] is nonzero.
 487
 488
 489 Available properties:
 490
 491 name               type      min     max     get set step comment
 492 =================================================================
 493
 494 osdlevel           int       0       3       X   X   X    as -osdlevel
 495 speed              float     0.01    100     X   X   X    as -speed
 496 loop               int       -1              X   X   X    as -loop
 497 hr_seek            string                    X   X   X    as -hr-seek
 498 pts_association_mode string                  X   X   X    as -pts-association-mode
 499 pause              flag      0       1       X            1 if paused
 500 filename           string                    X            file playing wo path
 501 path               string                    X            file playing
 502 media_title        string                    X            filename or libquvi QUVIPROP_PAGETITLE
 503 demuxer            string                    X            demuxer used
 504 stream_path        string                    X            filename (full path) of stream layer filename
 505 stream_pos         pos       0               X   X        position in stream
 506 stream_start       pos       0               X            start pos in stream
 507 stream_end         pos       0               X            end pos in stream
 508 stream_length      pos       0               X            (end - start)
 509 stream_time_pos    time      0               X            present position in stream (in seconds)
 510 chapter            int       0               X   X   X    select chapter
 511 chapters           int                       X            number of chapters
 512 angle              int       0               X   X   X    select angle
 513 length             time                      X            length of file in seconds
 514 percent_pos        int       0       100     X   X   X    position in percent
 515 time_pos           time      0               X   X   X    position in seconds
 516 metadata           str list                  X            list of metadata key/value
 517 metadata/*         string                    X            metadata values
 518 volume             float     0       100     X   X   X    change volume
 519 balance            float     -1      1       X   X   X    change audio balance
 520 mute               flag      0       1       X   X   X
 521 audio_delay        float     -100    100     X   X   X
 522 audio_format       int                       X
 523 audio_codec        string                    X
 524 audio_bitrate      int                       X
 525 samplerate         int                       X
 526 channels           int                       X
 527 switch_audio       int       -2      255     X   X   X    select audio stream
 528 switch_angle       int       -2      255     X   X   X    select DVD angle
 529 switch_title       int       -2      255     X   X   X    select DVD title
 530 capturing          flag      0       1       X   X   X    dump primary stream if enabled
 531 fullscreen         flag      0       1       X   X   X
 532 deinterlace        flag      0       1       X   X   X
 533 ontop              flag      0       1       X   X   X
 534 rootwin            flag      0       1       X   X   X
 535 border             flag      0       1       X   X   X
 536 framedropping      int       0       2       X   X   X    1 = soft, 2 = hard
 537 gamma              int       -100    100     X   X   X
 538 brightness         int       -100    100     X   X   X
 539 contrast           int       -100    100     X   X   X
 540 saturation         int       -100    100     X   X   X
 541 hue                int       -100    100     X   X   X
 542 panscan            float     0       1       X   X   X
 543 vsync              flag      0       1       X   X   X
 544 colormatrix        choice                    X   X   X    as --colormatrix
 545 colormatrix_input_range choice               X   X   X    as --colormatrix-input-range
 546 colormatrix_output_range choice              X   X   X    as --colormatrix-output-range
 547 video_format       int                       X
 548 video_codec        string                    X
 549 video_bitrate      int                       X
 550 width              int                       X            "display" width
 551 height             int                       X            "display" height
 552 fps                float                     X
 553 aspect             float                     X
 554 switch_video       int       -2      255     X   X   X    select video stream
 555 switch_program     int       -1      65535   X   X   X    (see TAB default keybind)
 556 sub                int       -1              X   X   X    select subtitle stream
 557 sub_source         int       -1      2       X   X   X    select subtitle source
 558 sub_file           int       -1              X   X   X    select file subtitles
 559 sub_vob            int       -1              X   X   X    select vobsubs
 560 sub_demux          int       -1              X   X   X    select subs from demux
 561 sub_delay          float                     X   X   X
 562 sub_pos            int       0       100     X   X   X    subtitle position
 563 sub_alignment      int       0       2       X   X   X    subtitle alignment
 564 sub_visibility     flag      0       1       X   X   X    show/hide subtitles
 565 sub_forced_only    flag      0       1       X   X   X
 566 sub_scale          float     0       100     X   X   X    subtitles font size
 567 ass_vsfilter_aspect_compat flag 0    1       X   X   X    SSA/ASS aspect ratio correction
 568 tv_brightness      int       -100    100     X   X   X
 569 tv_contrast        int       -100    100     X   X   X
 570 tv_saturation      int       -100    100     X   X   X
 571 tv_hue             int       -100    100     X   X   X
 572 teletext_page      int       0       799     X   X   X
 573 teletext_subpage   int       0       64      X   X   X
 574 teletext_mode      flag      0       1       X   X   X    0 - off, 1 - on
 575 teletext_format    int       0       3       X   X   X    0 - opaque,
 576                                                           1 - transparent,
 577                                                           2 - opaque inverted,
 578                                                           3 - transp. inv.
 579 teletext_half_page int       0       2       X   X   X    0 - off, 1 - top half,
 580                                                           2- bottom half