# XJADEO - Remote Control Interface

Xjadeo features a remote control mode that allows you to modify all settings of a running Xjadeo instance. When started in remote mode (using the `-R` or `--remote` option) xjadeo will interactively accept commands and issue responses through the standard input/output mechanism.

## Remote Control Variants

Since version 0.3.20 Xjadeo implements POSIX message queues (option `-Q`) as an alternative to the standard-I/O remote control and since 0.4.11 also System-V IPC (option `-W`. These allow one to disconnect from and re-connect to an existing xjadeo session. For more information about message queues see the xjremote(1) manual page.

Xjadeo's remote control interpreter is self documenting, use the `help` command to query the available command set.

## Response Format

Each remote command is acknowledged with a response. It is intended to be both human readable and machine parse-able. The response is a single line terminated with the newline character '\n' formatted as:

    @<status-integer> <text>

Every line start with a literal '@' followed by an integer which indicates if the command succeeded and specifies the format of the trailing text that is separated by a single whitespace from the number.

The status integer is a 3 digit decimal number in [100..999]:

1xx:
  OK. The command succeeded returning a small text info message.
2xx:
  The command succeeded and the return text is in format `key=value`. The range [200-299] further defines the type of the value as follows:
  201:
    integer
  202:
    double
  210:
    Two dimensional vector `intxint`
  220:
    Text string
  228:
    Tiemcode in format `HH:MM:SS:FF`
3xx:
  These are messages that are generated asynchronously by xjadeo (not in response to a command) after subscribing to notifications. The format and type declaration is identical to 2xx messages. Currently the only 3xx message is @301 position=integer.
4xx:
  Error message.
8xx:
  Info or help message. These messages are meant to be ignored by automatic parsers and are for user information or displaying comments only.

## Supported Commands

The following list was auto-generated from the `help` command:

seek `int`
  seek to this frame - if jack and midi are offline
load `filename`
  replace current video file
unload
  close video file
window close
  close window
window open
  open window
window mode `int`
  change video mode and open window
window resize `int` | `int` x `int`
  resize window (percent of movie or absolute size)
window size `int` | `int` x `int`
  alias for resize
window position `int` x `int`
  move window to given position (top-left coordinates)
window pos `int` x `int`
  alias for 'window position'
window xy `int` x `int`
  alias for 'window position'
window fullscreen `[on|off|toggle]`
  en/disable full screen
window zoom `[on|off|toggle]`
  alias for 'window full screen'
window letterbox `[on|off|toggle]`
  don't break aspect ratio
window mouse `[on|off|toggle]`
  en/disable mouse cursor display
window ontop `[on|off|toggle]`
  en/disable 'on top'
window fixaspect
  scale window to match aspect ration
osd frame `ypos`
  render current frame number. y=0..100 (negative integer: disable)
osd smpte `ypos`
  render sync timecode. y=0..100 (negative integer: disable)
osd text `text`
  render `text` on screen
osd text
  display prev. OSD text
osd notext
  clear text OSD
osd off
  same as 'osd notext'
osd on
  same as 'osd text'
osd pos `xalign` `ypos`
  xalign=0..2 (L,C,R) ypos=0..100
osd available
  return 100 if freetype OSD is available
osd font `filename`
  use this TTF font file
osd box
  forces a black box around the OSD
osd nobox
  transparent OSD background
osd mode `int`
  restore OSD as returned by 'get osdcfg'
jack connect
  connect and sync to jack server
jack disconnect
  disconnect from jack server
jack status
  get status of jack connection
midi connect `port`
  connect to midi time source (-1: discover)
midi disconnect
  close midi device
midi reconnect
  connect to last specified midi port
midi status
  display status of midi connection
midi driver `name`
  select midi driver
midi driver
  display the used midi driver
midi library
  alias for 'midi driver' (deprecated)
midi sync `int`
  set MTC smpte conversion. 0:MTC 2:Video 3:resample
midi clk `[1|0]`
  use MTC quarter frames
ltc connect
  connect and sync to LTC server
ltc disconnect
  disconnect from LTC
ltc status
  get status of jack connection
notify disable
  disable async messages
notify off
  alias for 'disable'
notify frame
  subscribe to async frame-update messages
notify keyboard
  subscribe to async key-press notifications
notify loop
  enable continuous frame position messages
notify settings
  receive a dump of current settings when xjadeo shuts down
notify noframe
  stop frame-update message subscription
notify noloop
  disable continuous frame position messages
notify nokeyboard
  disable async key-press notification messages
notify nosettings
  disable async settings dump on shutdown
get position
  return current frame position
get smpte
  return current frame position
get fps
  display current update frequency
get offset
  show current frame offset
get timescale
  show scale/offset
get loop
  show loop/wrap-around setting
get file
  print filename of current video buffer
get duration
  query length of video buffer in seconds
get frames
  show length of video buffer in frames
get framerate
  show frame rate of video file
get width
  query width of video source buffer
get height
  query width of video source buffer
get seekmode
  deprecated - no return value
get windowsize
  show current window size
get windowpos
  show current window position
get videomode
  display current video mode
get midisync
  display midi SMPTE conversion mode
get midiclk
  MTC quarter frame precision
get osdcfg
  display status on screen display
get syncsource
  display currently used sync source
get letterbox
  query video scaling mode
get fullscreen
  is xjadeo displayed on full screen
get ontop
  query window on top mode
get override
  query disabled window events
get version
  query xjadeo version
set offset `int`
  set timecode offset in frames
set fps `float`
  set screen update frequency
set framerate
  deprecated - no operation
set override `int`
  disable user-interaction (bitmask)
set seekmode
  deprecated - no operation
set timescale `float` `int`
  set timescale and offset (*)
set loop `int`
  0: normal, 1:wrap around (*)
reverse
  set timescale to reverse playback (*)
list videomodes
  displays a list of available video modes
ping
  claim a pong
help
  generate this remote-control API documentation
exit
  close remote-session (keep xjadeo running, with MQ and IPC)
quit
  terminate xjadeo