Difference between revisions of "Frontend control socket"

From MythTV Official Wiki
Jump to: navigation, search
m (set correct changeset)
m (Used By: Added MythControl entry)
(15 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Release [[Release_Notes_-_0.19|0.19]] of MythTV introduced the ability to control mythfrontend via a socket interface. Commands are sent and replies are received in text mode, there is no fancy xml interface or anything - it is meant to be able to be used via something as simple as telnet.  This feature has to be enabled in the general settings of the [[frontend]] setup. The default port is 6546, so after restarting mythfrontend, you can test by telnetting to localhost on port 6546  
+
Release [[Release_Notes_-_0.19|0.19]] of MythTV introduced the ability to control mythfrontend via a socket interface. Commands are sent and replies are received in text mode, there is no fancy xml interface or anything - it is meant to be able to be used via something as simple as netcat.  This feature has to be enabled in the general settings of the [[Mythfrontend|frontend]] setup. The default port is 6546, so after restarting mythfrontend, you can test by netcatting to localhost on port 6546  
<pre>telnet localhost 6546</pre>
+
<pre>netcat localhost 6546</pre>
  
See also [http://www.mythtv.org/docs/mythtv-HOWTO-11.html#ss11.5 MythTV docs on Telnet socket ]
+
See also [http://www.mythtv.org/docs/mythtv-HOWTO-11.html#ss11.5 MythTV docs on control socket ]
  
 +
{{Warning box|The frontend control socket does '''NOT''' implement the telnet protocol.  It is a raw text-based TCP socket.  The Telnet protocol expects certain behaviors and enforces 7-bit ASCII text, which the control socket does not follow and will cause complications if used.  '''netcat''' exists as a nearly drop-in replacement for telnet, and will work fine for this purpose.}}
  
= Supported Commands =
+
 
 +
== Supported Commands ==
 
For a list of supported commands, type "help". For help on a specific command, type "help COMMAND" (where COMMAND is the name of the command like "help jump").
 
For a list of supported commands, type "help". For help on a specific command, type "help COMMAND" (where COMMAND is the name of the command like "help jump").
== jump ==
+
=== jump ===
 
<pre>
 
<pre>
 
Usage: jump JUMPPOINT
 
Usage: jump JUMPPOINT
Line 52: Line 54:
 
viewscheduled        - Manage Recordings / Fix Conflicts
 
viewscheduled        - Manage Recordings / Fix Conflicts
 
</pre>
 
</pre>
== key ==
+
=== key ===
 
<pre>
 
<pre>
 
key LETTER          - Send the letter key specified
 
key LETTER          - Send the letter key specified
Line 68: Line 70:
 
== play ==
 
== play ==
 
<pre>
 
<pre>
play channel up       - Change channel Up
+
play volume NUMBER%    - Change volume to given percentage value
play channel down     - Change channel Down
+
play channel up       - Change channel Up
play channel NUMBER   - Change to a specific channel number
+
play channel down     - Change channel Down
play chanid NUMBER   - Change to a specific channel id (chanid)
+
play channel NUMBER   - Change to a specific channel number
play file FILENAME   - Play specified file
+
play chanid NUMBER     - Change to a specific channel id (chanid)
play program CHANID yyyy-mm-ddThh:mm:ss
+
play file FILENAME     - Play FILENAME (FILENAME may be a file or a myth:// URL)
                      - Play program with chanid & starttime
+
play program CHANID yyyy-MM-ddThh:mm:ss
play program CHANID yyyy-mm-ddThh:mm:ss resume
+
                      - Play program with chanid & starttime
                      - Resume program with chanid & starttime
+
play program CHANID yyyy-MM-ddThh:mm:ss resume
play save screenshot FILENAME
+
                      - Resume program with chanid & starttime
                      - Save screenshot from current position
+
play save preview
play seek beginning   - Seek to the beginning of the recording
+
                      - Save preview image from current position
play seek forward     - Skip forward in the video
+
play save preview FILENAME
play seek backward   - Skip backwards in the video
+
                      - Save preview image to FILENAME
play seek HH:MM:SS   - Seek to a specific position
+
play save preview FILENAME WxH
play speed pause     - Pause playback
+
                      - Save preview image of size WxH
play speed normal     - Playback at normal speed
+
play seek beginning   - Seek to the beginning of the recording
play speed 1x         - Playback at normal speed
+
play seek forward     - Skip forward in the video
play speed -1x        - Playback at normal speed in reverse
+
play seek backward     - Skip backwards in the video
play speed 1/16x      - Playback at 1/16x speed
+
play seek HH:MM:SS     - Seek to a specific position
play speed 1/8x      - Playback at 1/8x speed
+
play speed pause       - Pause playback
play speed 1/4x      - Playback at 1/4x speed
+
play speed normal     - Playback at normal speed
play speed 1/2x       - Playback at 1/2x speed
+
play speed 1x         - Playback at normal speed
play speed 2x        - Playback at 2x speed
+
play speed SPEEDx      - Playback where SPEED must be a decimal
play speed 4x        - Playback at 4x speed
+
play speed 1/8x        - Playback at 1/8x speed
play speed 8x        - Playback at 8x speed
+
play speed 1/4x        - Playback at 1/4x speed
play speed 16x       - Playback at 16x speed
+
play speed 1/3x        - Playback at 1/3x speed
play stop            - Stop playback
+
play speed 1/2x       - Playback at 1/2x speed
 +
play stop              - Stop playback
 +
play music play        - Resume playback (MythMusic)
 +
play music pause      - Pause playback (MythMusic)
 +
play music stop       - Stop Playback (MythMusic)
 +
play music setvolume N - Set volume to number (MythMusic)
 +
play music getvolume  - Get current volume (MythMusic)
 +
play music getmeta    - Get metadata for current track (MythMusic)
 +
play music file NAME  - Play specified file (MythMusic)
 +
play music track N    - Switch to specified track (MythMusic)
 +
play music url URL    - Play specified URL (MythMusic)
 
</pre>
 
</pre>
  
== query ==
+
=== query ===
 
<pre>
 
<pre>
query location        - Query current screen or location (i.e. MainMenu)
+
query location        - Query current screen or location
 +
query volume          - Query the current playback volume
 
query recordings      - List currently available recordings
 
query recordings      - List currently available recordings
 
query recording CHANID STARTTIME
 
query recording CHANID STARTTIME
Line 106: Line 119:
 
query liveTV          - List current TV schedule
 
query liveTV          - List current TV schedule
 
query liveTV CHANID  - Query current program for specified channel
 
query liveTV CHANID  - Query current program for specified channel
query time            - Query current time on server
+
query load            - List 1/5/15 load averages
 +
query memstats        - List free and total, physical and swap memory
 +
query time            - Query current time on frontend
 +
query uptime          - Query machine uptime
 +
query verbose        - Get current VERBOSE filter
 +
query version        - Query Frontend version details
 +
query channels        - Query available channels
 +
query channels START LIMIT - Query available channels from START and limit results to LIMIT lines
 
</pre>
 
</pre>
  
== exit ==
+
=== exit ===
 
Terminates the session.
 
Terminates the session.
= Used By =
+
 
 +
== Limitations & Workarounds ==
 +
Some limitations exist in the front-end control protocol; especially with implementations that exist for plugins to MythTV. For instance it is not possible to list artists, albums or tracks in MythMusic, neither is it possible to add tracks to the current queue or change playback to something else without emulating key-presses, which requires knowledge of the exact position of the cursor by the application.
 +
 
 +
MythMusic Rescan Workaround: It is not possible to have MythMusic re-scan for music; although it is possible to emulate this behaviour. Using MythWeb, go to settings -> MythTV -> Key bindings and select the host  (or hosts) from the drop-down you would like to be able to initiate a rescan programatically. Look up the row called "Scan Music". add a Key you would like to use (make sure it isnt a key you require elsewhere in the application as this is a global key-binding. Save the changes, you may need to restart the front-end in question. send the relevant key-press via the network control port to initiate music-rescan. i.e. nc localhost 6546  then if you used F6; # key f6
 +
 
 +
The above can also be done from a script, like so:
 +
 
 +
<pre>
 +
nc localhost 6546 -i 1 <<EOS
 +
key f6
 +
quit
 +
EOS
 +
</pre>
 +
 
 +
== IP Address availability ==
 +
As of 0.25, this feature now follows the IP settings for the current machine's profile, if configured in `mythtv-setup`. These are the BackendServerIP and BackendServerIP6 settings on the first page of the General section. If these settings are left blank, as would be the case on a dedicated frontend if the user had never run `mythtv-setup`, or if the defaults in those fields were intentionally blanked, this feature will automatically be available on all IPv6 address, and all private network IPv4 addresses. Per [http://tools.ietf.org/html/rfc1918 RFC1918], those addresses are:
 +
 
 +
* 10.0.0.0 - 10.255.255.255
 +
* 172.16.0.0 - 172.31.255.255
 +
* 192.168.0.0 - 192.168.255.255
 +
 
 +
Most users will find themselves within that last group of IP addresses.
 +
 
 +
If one wishes to restrict the addresses that the control socket is available through, defining those fields in `mythtv-setup` will cause the control socket to only be available on those two addresses. Similarly, those can be used to select an IPv4 address outside those private network ranges. If one wants to unrestrict where the frontend listens, but is running on a combination frontend/backend, where `mythbackend` required those options be set for proper operation, the frontend can be forced to run on an independent machine profile. That value defaults to the current machine hostname. In 0.25, that value can be overridden using the LocalHostName parameter in mysql.txt as follows:
 +
 
 +
{{code box|~/.mythtv/mysql.txt|
 +
<pre>
 +
...
 +
LocalHostName=myindependentfrontendprofilestring
 +
...
 +
</pre>
 +
}}
 +
 
 +
In 0.26 and later, mysql.txt has been removed in favor of config.xml, which can be configured as follows:
 +
 
 +
{{code box|~/.mythtv/config.xml|
 +
<pre>
 +
<Configuration>
 +
  ...
 +
  <LocalHostName>myindependentfrontendprofilestring</LocalHostName>
 +
  ...
 +
</Configuration>
 +
</pre>
 +
}}
 +
 
 +
== Used By ==
 
{| border="1" cellpadding="5" cellspacing="0"
 
{| border="1" cellpadding="5" cellspacing="0"
 
|-
 
|-
Line 119: Line 185:
 
|Python class for interfacing with the frontend socket.
 
|Python class for interfacing with the frontend socket.
 
|-
 
|-
|[http://svn.mythtv.org/trac/browser/trunk/mythtv/contrib/remotes/tkmythremote tkmythremote]
+
|[[tkmythremote]]
 
|Simple graphical interface implemented in wish/tk
 
|Simple graphical interface implemented in wish/tk
 
|-
 
|-
|[http://svn.mythtv.org/trac/browser/trunk/mythtv/contrib/remotes/mythremctl mythremctl]
+
|[[mythremctl.py]]
 
|Curses based remote written in python
 
|Curses based remote written in python
 
|-
 
|-
Line 141: Line 207:
 
|[http://www.cs.mu.oz.au/~aaron/mythtvmobileremote.html MythTV Mobile Remote]
 
|[http://www.cs.mu.oz.au/~aaron/mythtvmobileremote.html MythTV Mobile Remote]
 
|Graphical remote for Nokia N80
 
|Graphical remote for Nokia N80
 +
|-
 +
|[http://code.google.com/p/webmyth/ WebMyth]
 +
|Remote and scheduler for HP webOS phones (e.g. Palm Pre)
 +
|-
 +
|[http://code.google.com/p/mythme-wp7/ MythMe]
 +
|Remote and scheduler for windows Phone 7
 
|-
 
|-
 
|[[Controlling_MythTV_from_any_phone_using_Asterisk|Asterisk]]
 
|[[Controlling_MythTV_from_any_phone_using_Asterisk|Asterisk]]
Line 150: Line 222:
 
|[http://kylestoneman.com/out/remote.tar.gz iPhone Remote]
 
|[http://kylestoneman.com/out/remote.tar.gz iPhone Remote]
 
|Another simple web-based remote
 
|Another simple web-based remote
 +
|-
 +
|[http://dairystatedesigns.com/mythcontrol MythControl]
 +
|Remote control and recordings manager for iPhone
 
|-
 
|-
 
|[http://dev-scene.com/NDS/MythRemote MythRemote]
 
|[http://dev-scene.com/NDS/MythRemote MythRemote]
Line 185: Line 260:
 
|}
 
|}
  
= Development =
+
== Development ==
==Changeset {{changeset|8688}}==
+
=== Changeset {{gitcommit|7f3dcdab|mythtv|v0.17-2759-g7f3dcda}} ===
 
The initial implementation.
 
The initial implementation.
  
==Changeset {{changeset|12907}}==
+
=== Changeset {{gitcommit|d86cf6e0|mythtv|v0.20-1001-gd86cf6e}} ===
 
<pre>
 
<pre>
 
Modified:
 
Modified:
Line 220: Line 295:
 
"key down down sleep down enter"
 
"key down down sleep down enter"
 
</pre>
 
</pre>
==Changeset {{changeset|22514}}==
+
=== Changeset {{gitcommit|4f40c42f|mythtv|v0.20-8059-g4f40c42}} ===
Telnet socket now supports multiple simultaneous connections. Previous behavior was to terminate existing connections when a new one was made.
+
Control socket now supports multiple simultaneous connections. Previous behavior was to terminate existing connections when a new one was made.
 +
 
 +
=== Changeset {{gitcommit|7422f241a9c62|mythtv|v0.25pre-446-g7422f24}} ===
 +
Add playback functions for control of MythMusic.
 +
 
 
[[Category:HOWTO]]
 
[[Category:HOWTO]]
 
[[Category:Developer Documentation]]
 
[[Category:Developer Documentation]]

Revision as of 17:11, 17 December 2012

Release 0.19 of MythTV introduced the ability to control mythfrontend via a socket interface. Commands are sent and replies are received in text mode, there is no fancy xml interface or anything - it is meant to be able to be used via something as simple as netcat. This feature has to be enabled in the general settings of the frontend setup. The default port is 6546, so after restarting mythfrontend, you can test by netcatting to localhost on port 6546

netcat localhost 6546

See also MythTV docs on control socket

Warning.png Warning: The frontend control socket does NOT implement the telnet protocol. It is a raw text-based TCP socket. The Telnet protocol expects certain behaviors and enforces 7-bit ASCII text, which the control socket does not follow and will cause complications if used. netcat exists as a nearly drop-in replacement for telnet, and will work fine for this purpose.


Supported Commands

For a list of supported commands, type "help". For help on a specific command, type "help COMMAND" (where COMMAND is the name of the command like "help jump").

jump

Usage: jump JUMPPOINT

Where JUMPPOINT is one of the following:
channelpriorities    - Channel Recording Priorities
channelrecpriority   - Channel Recording Priorities
deletebox            - TV Recording Deletion
deleterecordings     - TV Recording Deletion
flixbrowse           - Netflix Browser
flixhistory          - Netflix History
flixqueue            - Netflix Queue
guidegrid            - Program Guide
livetv               - Live TV
livetvinguide        - Live TV In Guide
mainmenu             - Main Menu
managerecordings     - Manage Recordings / Fix Conflicts
manualbox            - Manual Record Scheduling
manualrecording      - Manual Record Scheduling
musicplaylists       - Select music playlists
mythgallery          - MythGallery
mythgame             - MythGame
mythmovietime        - MythMovieTime
mythnews             - MythNews
mythvideo            - MythVideo
mythweather          - MythWeather
playbackbox          - TV Recording Playback
playbackrecordings   - TV Recording Playback
playdvd              - Play DVD
playmusic            - Play music
previousbox          - Previously Recorded
progfinder           - Program Finder
programfinder        - Program Finder
programguide         - Program Guide
programrecpriority   - Program Recording Priorities
recordingpriorities  - Program Recording Priorities
ripcd                - Rip CD
ripdvd               - Rip DVD
statusbox            - Status Screen
videobrowser         - Video Browser
videogallery         - Video Gallery
videolistings        - Video Listings
videomanager         - Video Manager
viewscheduled        - Manage Recordings / Fix Conflicts

key

key LETTER           - Send the letter key specified
key NUMBER           - Send the number key specified
key CODE             - Send one of the following key codes

Supported keys:

#, $, %, &, (, ), *, +, ,, -, ., /, :, ;, <, =, >, ?, [, \, ], ampersand, asterisk, backslash, backspace, 
backtab, bar, bracketleft, bracketright, colon, comma, delete, dollar, down, end, enter, equal, escape, 
f1, f10, f11, f12, f13, f14, f15, f16, f17, f18, f19, f2, f20, f21, f22, f23, f24, f3, f4, f5, f6, f7, f8, f9, 
greater, home, insert, left, less, minus, numbersign, pagedown, pageup, parenleft, parenright, percent, 
period, pipe, plus, poundsign, question, return, right, semicolon, slash, space, tab, up, |

play

play volume NUMBER%    - Change volume to given percentage value
play channel up        - Change channel Up
play channel down      - Change channel Down
play channel NUMBER    - Change to a specific channel number
play chanid NUMBER     - Change to a specific channel id (chanid)
play file FILENAME     - Play FILENAME (FILENAME may be a file or a myth:// URL)
play program CHANID yyyy-MM-ddThh:mm:ss
                       - Play program with chanid & starttime
play program CHANID yyyy-MM-ddThh:mm:ss resume
                       - Resume program with chanid & starttime
play save preview
                       - Save preview image from current position
play save preview FILENAME
                       - Save preview image to FILENAME
play save preview FILENAME WxH
                       - Save preview image of size WxH
play seek beginning    - Seek to the beginning of the recording
play seek forward      - Skip forward in the video
play seek backward     - Skip backwards in the video
play seek HH:MM:SS     - Seek to a specific position
play speed pause       - Pause playback
play speed normal      - Playback at normal speed
play speed 1x          - Playback at normal speed
play speed SPEEDx      - Playback where SPEED must be a decimal
play speed 1/8x        - Playback at 1/8x speed
play speed 1/4x        - Playback at 1/4x speed
play speed 1/3x        - Playback at 1/3x speed
play speed 1/2x        - Playback at 1/2x speed
play stop              - Stop playback
play music play        - Resume playback (MythMusic)
play music pause       - Pause playback (MythMusic)
play music stop        - Stop Playback (MythMusic)
play music setvolume N - Set volume to number (MythMusic)
play music getvolume   - Get current volume (MythMusic)
play music getmeta     - Get metadata for current track (MythMusic)
play music file NAME   - Play specified file (MythMusic)
play music track N     - Switch to specified track (MythMusic)
play music url URL     - Play specified URL (MythMusic)

query

query location        - Query current screen or location
query volume          - Query the current playback volume
query recordings      - List currently available recordings
query recording CHANID STARTTIME
                      - List info about the specified program
query liveTV          - List current TV schedule
query liveTV CHANID   - Query current program for specified channel
query load            - List 1/5/15 load averages
query memstats        - List free and total, physical and swap memory
query time            - Query current time on frontend
query uptime          - Query machine uptime
query verbose         - Get current VERBOSE filter
query version         - Query Frontend version details
query channels        - Query available channels
query channels START LIMIT - Query available channels from START and limit results to LIMIT lines

exit

Terminates the session.

Limitations & Workarounds

Some limitations exist in the front-end control protocol; especially with implementations that exist for plugins to MythTV. For instance it is not possible to list artists, albums or tracks in MythMusic, neither is it possible to add tracks to the current queue or change playback to something else without emulating key-presses, which requires knowledge of the exact position of the cursor by the application.

MythMusic Rescan Workaround: It is not possible to have MythMusic re-scan for music; although it is possible to emulate this behaviour. Using MythWeb, go to settings -> MythTV -> Key bindings and select the host (or hosts) from the drop-down you would like to be able to initiate a rescan programatically. Look up the row called "Scan Music". add a Key you would like to use (make sure it isnt a key you require elsewhere in the application as this is a global key-binding. Save the changes, you may need to restart the front-end in question. send the relevant key-press via the network control port to initiate music-rescan. i.e. nc localhost 6546 then if you used F6; # key f6

The above can also be done from a script, like so:

nc localhost 6546 -i 1 <<EOS
key f6
quit
EOS

IP Address availability

As of 0.25, this feature now follows the IP settings for the current machine's profile, if configured in `mythtv-setup`. These are the BackendServerIP and BackendServerIP6 settings on the first page of the General section. If these settings are left blank, as would be the case on a dedicated frontend if the user had never run `mythtv-setup`, or if the defaults in those fields were intentionally blanked, this feature will automatically be available on all IPv6 address, and all private network IPv4 addresses. Per RFC1918, those addresses are:

  • 10.0.0.0 - 10.255.255.255
  • 172.16.0.0 - 172.31.255.255
  • 192.168.0.0 - 192.168.255.255

Most users will find themselves within that last group of IP addresses.

If one wishes to restrict the addresses that the control socket is available through, defining those fields in `mythtv-setup` will cause the control socket to only be available on those two addresses. Similarly, those can be used to select an IPv4 address outside those private network ranges. If one wants to unrestrict where the frontend listens, but is running on a combination frontend/backend, where `mythbackend` required those options be set for proper operation, the frontend can be forced to run on an independent machine profile. That value defaults to the current machine hostname. In 0.25, that value can be overridden using the LocalHostName parameter in mysql.txt as follows:


Script.png ~/.mythtv/mysql.txt

...
LocalHostName=myindependentfrontendprofilestring
...

In 0.26 and later, mysql.txt has been removed in favor of config.xml, which can be configured as follows:


Script.png ~/.mythtv/config.xml

<Configuration>
  ...
  <LocalHostName>myindependentfrontendprofilestring</LocalHostName>
  ...
</Configuration>

Used By

Official
Python bindings Python class for interfacing with the frontend socket.
tkmythremote Simple graphical interface implemented in wish/tk
mythremctl.py Curses based remote written in python
MythWeb On screen and passthrough keyboard available in MythWeb
Mobile
MyMote Remote control and scheduler for the iPhone.
Mythetomer Graphical remote for Nokia Internet Tablets and Smartphones
MythMote Graphical remote for Android powered devices
MythTV Mobile Remote Graphical remote for Nokia N80
WebMyth Remote and scheduler for HP webOS phones (e.g. Palm Pre)
MythMe Remote and scheduler for windows Phone 7
Asterisk Remote control using any touchtone phone through Asterisk.
MythTV Web Remote Simple graphical web-based remote
iPhone Remote Another simple web-based remote
MythControl Remote control and recordings manager for iPhone
MythRemote Homebrew Nintendo DS remote
Windows Mobile via MythControl Windows Mobile remote
irreco A remote control application for Nokia Internet Tablets.
PC
MythRemote Graphical remote for OSX
DirectTV D11 Channel for controlling mythtv with a D11 remote
RemoteKommander Graphical remote for KDE
MythRemote Control Graphical remote written in Python/PythonCard
RocketRemote Graphical remote written in Adobe Flex
MythRemote Graphical remote written in Perl/Tk
cmdline-mythremote Very simple command line remote written in C

Development

Changeset [v0.17-2759-g7f3dcda]cgitgithub

The initial implementation.

Changeset [v0.20-1001-gd86cf6e]cgitgithub

Modified:

trunk/mythtv/programs/mythfrontend/networkcontrol.cpp

Log:

Network Control socket interface changes.

Add some new valid keys. The list:
home, end, return, tab, backtab, insert, delete, plus, comma, minus,
period, numbersign (aka poundsign), dollar, percent, ampersand, parenleft,
parenright, asterisk, question, bar, pipe, and F13 through F24. This also
adds the ability to use the actual symbol for mose of these such as "key +"
instead of having to type "key plus".

Add the ability to send key combinations such as CTRL+B, ALT+F, etc.. The
four supported modifiers are CTRL, ALT, SHIFT, and META and they can be
used individually such as CTRL+B or together such as CTRL+ALT+B.

Fix some minor bugs related to case conversion, previously the code would
lower() the whole input command and then uppercase the few places that
needed it such as when passing a Qt::ISODateTime, now we just lower() when
comparing things that need case-insensitive comparisons.

For debugging purposes, add the ability to sleep in the middle of a key
combination. You can now use the keyword 'sleep' to sleep one second in
the middle of a key command. Here's a not-so-useful example:
"key down down sleep down enter"

Changeset [v0.20-8059-g4f40c42]cgitgithub

Control socket now supports multiple simultaneous connections. Previous behavior was to terminate existing connections when a new one was made.

Changeset [v0.25pre-446-g7422f24]cgitgithub

Add playback functions for control of MythMusic.