Difference between revisions of "MythTV System Events"

From MythTV Official Wiki
Jump to: navigation, search
(Link to Category:MythTV_System_Event_Scripts page)
m (Make note match User Jobs note)
 
(5 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
MythTV System Events are a new feature in MythTV 0.23. Historically MythEvents have been used to communicate between components of the system when blocking was not required for proper operation. Now it is possible for the end user to tap into a number of events as well as defining up to ten keypress events. These events are handled by running an external script with appropriate parameters. MythTV System Events are configured on a per box basis so each machine can have it's own system specific handlers.
 
MythTV System Events are a new feature in MythTV 0.23. Historically MythEvents have been used to communicate between components of the system when blocking was not required for proper operation. Now it is possible for the end user to tap into a number of events as well as defining up to ten keypress events. These events are handled by running an external script with appropriate parameters. MythTV System Events are configured on a per box basis so each machine can have it's own system specific handlers.
 +
 +
{{Note box| Beginning with release 0.26, timestamps of recordings are stored in UTC. Applications that use xxxTIME parameters to directly index the database will need to either handle timezone conversion internally, or switch to the respective xxxTIMEUTC parameters. See [[UTC]]}}
 +
<br>
 +
== Available Events ==
  
 
These are the currently defined events:
 
These are the currently defined events:
 +
 
* Recording pending
 
* Recording pending
 
* Recording started
 
* Recording started
Line 7: Line 12:
 
* Recording deleted
 
* Recording deleted
 
* Recording expired
 
* Recording expired
 +
* LiveTV started
 
* Playback started
 
* Playback started
 
* Playback stopped
 
* Playback stopped
Line 49: Line 55:
 
The parameters that it is possible to pass to an event depends on the event.
 
The parameters that it is possible to pass to an event depends on the event.
  
Recording events have the following substitutions available:
+
{{Event_and_Job_Parameters}}
* %DIR% -- Recording directory, may be undefined prior to recording start
+
* %FILE% -- Recording file, may be undefined prior to recording start
+
* %TITLE% -- Program title, may be undefined
+
* %SUBTITLE% -- Program subtitle, may be undefined
+
* %DESCRIPTION% -- Program title, may be undefined
+
* %CATEGORY% -- Program subject category, may be undefined
+
* %HOSTNAME% -- Backend which will or is handling the recording
+
* %RECGROUP% -- Recording group for recording
+
* %PLAYGROUP% -- Play group for recording
+
* %CHANID% -- Channel ID (for database lookups of tuning data)
+
* %STARTTIME% %STARTTIMEISO% %STARTTIMEISOUTC% -- Recording start time (estimated)
+
* %ENDTIME% %ENDTIMEISO% %ENDTIMEISOUTC%      -- Recording end time (estimated)
+
* %PROGSTART% %PROGSTARTISO% %PROGSTARTISOUTC% -- Program's scheduled start time
+
* %PROGEND% %PROGENDISO% %PROGENDISOUTC%      -- Program's scheduled end time
+
* %RECID% -- Recording rule ID, for DB lookups
+
* %PARENTID% -- Parent recording rule ID, for DB lookups
+
* %FINDID% -- Find ID, for DB lookups
+
* %RECSTATUS% -- Recording status as an integer for completeness, not currently useful.
+
* %RECTYPE% -- This is the recording rule type as an integer, in the priming script example this could be used to do an extensive priming prior to some recordings and not others. These integers are listed in recordingtypes.h in the RecordingType enum.
+
* %REACTIVATE% -- 1 if this recording was reactivated after failing to start on time, 0 otherwise.
+
  
 
With time parameters, the first listed is in locale time & format suitable for user display, the second is in locale time & ISO format suitable for some scripts, the third is in UTC time & ISO format suitable for some script and generally preferred for scripts to avoid daylight savings issues. Parameters that may be undefined should be quoted to avoid parameter aliasing bugs.
 
With time parameters, the first listed is in locale time & format suitable for user display, the second is in locale time & ISO format suitable for some scripts, the third is in UTC time & ISO format suitable for some script and generally preferred for scripts to avoid daylight savings issues. Parameters that may be undefined should be quoted to avoid parameter aliasing bugs.

Latest revision as of 21:09, 17 September 2012

MythTV System Events are a new feature in MythTV 0.23. Historically MythEvents have been used to communicate between components of the system when blocking was not required for proper operation. Now it is possible for the end user to tap into a number of events as well as defining up to ten keypress events. These events are handled by running an external script with appropriate parameters. MythTV System Events are configured on a per box basis so each machine can have it's own system specific handlers.


Important.png Note: Beginning with release 0.26, timestamps of recordings are stored in UTC. Applications that use xxxTIME parameters to directly index the database will need to either handle timezone conversion internally, or switch to the respective xxxTIMEUTC parameters. See UTC


Available Events

These are the currently defined events:

  • Recording pending
  • Recording started
  • Recording finished
  • Recording deleted
  • Recording expired
  • LiveTV started
  • Playback started
  • Playback stopped
  • Playback paused
  • Playback unpaused
  • Playback program changed
  • Master backend started
  • Master backend shutdown
  • Client connected to master backend
  • Client disconnected from master backend
  • Slave backend connected to master
  • Slave backend disconnected from master
  • Network Control client connected
  • Network Control client disconnected
  • mythfilldatabase ran
  • Scheduler ran
  • Settings cache cleared

These events are all sent automatically when the appropriate condition is met, but it is also possible to send events from the command line, for example:

mythbackend --systemevent USER_1

sends the first user event to whatever handler has been defined for that event.

Defining event handlers

Events handlers are edited in the System Events section in mythtv-setup. Select the event you would like to edit in the event list and then type in the script path and name followed by any parameters that you would like to pass to the script. For example to run a script whenever a recording is pending you could select the "Recording pending" event and type:

/opt/bin/RecordingPending.sh %STARTTIME%

That script could be a priming script to get a set top box out of it's sleep mode:

#!/bin/bash
flock -x /tmp/chch.lock
DEVICE="--address=cherry:5000"
REMOTE_NAME=dish1
irsend $DEVICE SEND_ONCE $REMOTE_NAME select
echo "Sent priming shortly before %1" >> /tmp/priming-debug.log

Parameters available to event handlers

The parameters that it is possible to pass to an event depends on the event.


Parameters for System Events and User Jobs
Parameter Description Used

By

Released

In

%CARDID% Event
%CATEGORY% Program subject category, may be undefined. Both
%CHANID% Channel ID Both
%DESCRIPTION% Program title, may be undefined. Both
%DIR% Event: myth://IP:6543/file.mpg, Job: actual directory, may be undefined prior to recording start. Both
%ENDTIME% Recording end time (estimated) yyyyMMddhhmmss. Both
%ENDTIMEISO% YYYY-MM-DDThh:mm:ss Both
%ENDTIMEISOUTC% YYYY-MM-DDThh:mm:ssZ
%ENDTIMEUTC% yyyyMMddhhmmss Both
%FILE% Recording file, may be undefined prior to recording start. Both
%FINDID% Find ID, for DB lookups. Event
%HOSTNAME% Both
%JOBID% The id of this job in the mythconverg jobqueue table.
%ORIGINALAIRDATE% Original Air Date of recording. Both
%PARENTID% Parent recording rule ID, for DB lookups. Event
%PLAYGROUP% Play group Both
%PROGEND% Program's scheduled end time. Both
%PROGENDISO% Both
%PROGENDISOUTC%
%PROGENDUTC% Both
%PROGSTART% Both
%PROGSTARTISO% Both
%PROGSTARTISOUTC%
%PROGSTARTUTC% Both
%REACTIVATE% 1 if this recording was reactivated after failing to start on time, 0 otherwise. Event
%RECGROUP% Recording group Both
%RECID% Recording rule ID, for DB lookups. Event
%RECSTATUS% Recording status as an integer for completeness, not currently useful. Event
%RECTYPE% This is the recording rule type as an integer, in the priming script example this could be used to do an extensive priming prior to some recordings and not others. These integers are listed in recordingtypes.h in the RecordingType enum. Event
%SECS% Time until upcoming recording starts. Event
%SENDER% Origin of event (hostname.) Event
%STARTTIME% Both
%STARTTIMEISO% Both
%STARTTIMEISOUTC%
%STARTTIMEUTC% Both
%SUBTITLE% Program subtitle, may be undefined. Both
%TITLE% Program title, may be undefined. Both
%TRANSPROFILE% Profile number. Job
%VERBOSELEVEL% Bit mapped decimal value. Both
%VERBOSEMODE% Passes: --verbose --logpath --loglevel --quiet --nodblog [--syslog (if non Windows)]. Job 0.25

Note that not all parameters are available to all System Events User Jobs.


With time parameters, the first listed is in locale time & format suitable for user display, the second is in locale time & ISO format suitable for some scripts, the third is in UTC time & ISO format suitable for some script and generally preferred for scripts to avoid daylight savings issues. Parameters that may be undefined should be quoted to avoid parameter aliasing bugs.

Example Scripts

See the example scripts at Category:MythTV_System_Event_Scripts