Difference between revisions of "Mythlink.pl"

From MythTV Official Wiki
Jump to: navigation, search
(Start to move mythrename.pl info to mythlink.pl)
m (Replace "%STARTTIME%" with "%STARTTIMEUTC%". The former has the local time zone since 0.26, but mythlink.pl requires UTC times.)
 
(21 intermediate revisions by 8 users not shown)
Line 1: Line 1:
'''mythlink.pl''' is a Perl script (written by [[User:Xris | Chris Peterson]]) for creating human-readable symlinks to  MythTV recordings.  Once you have created a directory of readable symlinks, the show can be archived with the link's name using appropriate copy or move commands.
+
{{Script info
 +
|author=Chris Peterson
 +
|webpage=http://svn.mythtv.org/trac/browser/branches/release-0-23-fixes/mythtv/contrib/user_jobs/mythlink.pl
 +
|short=produces human-readable recording filenames
 +
|long=Creates symlinks to local recordings from a user defined
 +
|file=http://svn.mythtv.org/trac/export/24263/branches/release-0-23-fixes/mythtv/contrib/user_jobs/mythlink.pl
 +
|category=User Job Scripts
 +
|S23=yes|S24=yes|S25=yes|S26=yes|S27=yes}}
 +
 
 +
'''mythlink.pl''' is a Perl script (written by [[User:Xris | Chris Peterson]]) for creating human-readable symlinks to  MythTV recordings.  Once you have created a directory of readable symlinks, the show can be archived with the link's name using appropriate copy or move commands.
 +
 
 +
Whilst support for 0.26 and 0.27 is indicated above, a note from the developers (May 2014): "The Python bindings are the best way to create new scripts for MythTV, but no one has rewritten mythlink.pl functionality using the Python bindings (and doing so probably doesn't offer much of any benefit over the still-functional mythlink.pl), so it's still the best way to get user-friendly file-system views of your recordings. "
 +
 
 +
== Usage ==
  
==Usage==
 
 
Database and directory settings are automatically detected, so usage is as simple as:
 
Database and directory settings are automatically detected, so usage is as simple as:
  
 
  mythlink.pl --link [destination directory]
 
  mythlink.pl --link [destination directory]
  
Examples:
+
In the event that <code>[destination directory]</code> exists, mythlink.pl will first delete all symlinks underneath that directory and then begin creating new symlinks.  This will remove symlinks to recordings that have since been deleted.
 +
 
 +
Note that when specifying <code>--filename</code> or <code>--chanid</code> and <code>--starttime</code>, deletion of old symlinks is suppressed. Therefore, anyone using this script in a user job or with the event system should still run the script occasionally without the <code>--filename</code> or <code>--chanid</code> and <code>--starttime</code> arguments to allow removal of links that referred to recordings since deleted. Alternatively, you may use a script triggered on "Recording deleted" and "Recording expired" to remove the specific link when its recording is removed.
 +
 
 +
See <code>mythlink.pl --help</code> (as [[mythlink.pl#Help_Output|below]]) for more information.
 +
 
 +
== Examples ==
 +
 
 +
mythlink.pl --link /mnt/pretty --format '%T/%T%-%S'
 +
 
 +
creates links using the format <code>[title]/[title]-[subtitle]</code>
 +
 
 +
mythlink.pl --link /mnt/pretty --format '%Y%m%d-%H%i-%eH%ei-%T-%S'
 +
 
 +
creates links using the format <code>[startdate]-[starttime]-[endtime]-[title]-[subtitle]</code>
 +
 
 +
mythlink.pl --link /mnt/pretty --format '%T/%Y%m%d-%H%i-%eH%ei-%S'
 +
 
 +
creates links using the format <code>[title]/[startdate]-[starttime]-[endtime]-[subtitle]</code>
 +
 
 +
mythlink.pl --link /mnt/pretty --format '%U-%T-%Y%m%d-%H%i-%eH%ei-%S'
 +
 
 +
creates links using the format <code>[recgroup]-[title]-[startdate]-[starttime]-[endtime]-[subtitle]</code>
 +
 
 +
mythlink.pl --link /mnt/pretty --format '%C-%T-%Y%m%d-%H%i-%eH%ei-%S'
 +
 
 +
creates links using the format <code>[category]-[title]-[startdate]-[starttime]-[endtime]-[subtitle]</code>
 +
 
 +
mythlink.pl --link /mnt/pretty --format '%T-%oY%om%od-%S'
 +
 
 +
creates links using the format <code>[title]-[original airdate]-[subtitle]</code>
 +
 
 +
 
 +
== Using as a User Job ==
 +
 
 +
When used as a [[User_Jobs|User Job]], <code>mythlink.pl</code> will be executed when the recording ends, and can be configured such that it only creates a link for the new recording.  To use the script as a [[User_Jobs|User Job]], specify the <code>--chanid</code> and <code>--starttime</code> arguments in addition to any other desired arguments and it will create a link only for the new recording:
 +
 
 +
mythlink.pl --link /mnt/pretty --chanid "%CHANID%" --starttime "%STARTTIMEUTC%"  --format '%T/%T%-%S'
 +
{{Note box|You will also need to run mythlink.pl separately to remove old symlinks.  See [[mythlink.pl#Usage|Usage]].}}
 +
 
 +
== Using with MythTV System Events ==
  
  mythlink.pl --link /mnt/pretty --format '%T/%T%-%S'
+
When using the script with [[MythTV System Events]], <code>mythlink.pl</code> can be executed as soon as the recording begins, using the <code>Recording started</code> event.  To use the script with [[MythTV System Events]], specify the <code>--chanid</code> and <code>--starttime</code> arguments in addition to any other desired arguments, and it will create a link only for the new recording:
  
See <code>mythlink.pl --help</code> (as below) for more information.
+
mythlink.pl --link /mnt/pretty --chanid "%CHANID%" --starttime "%STARTTIMEUTC%"  --format '%T/%T%-%S'
 +
Users with a relatively slow storage device (eg on a nas drive) have found it necessary to delay starting mythlink.pl:
 +
sleep 10 && mythlink.pl --link /mnt/pretty --chanid "%CHANID%" --starttime "%STARTTIMEUTC%"  --format '%T/%T%-%S'
  
 +
{{Note box|You will also need to run mythlink.pl separately to remove old symlinks.  See [[mythlink.pl#Usage|Usage]].}}
  
 
== Help Output ==
 
== Help Output ==
Line 20: Line 75:
 
options:
 
options:
  
 +
--link [destination directory]
 
--dest [destination directory]
 
--dest [destination directory]
 +
--destination [destination directory]
 +
--path [destination directory]
 +
 +
    (This option can be given as --link, --dest, --destination or --path.
 +
    All of these alternatives produce the same behaviour.)
  
 
     Specify the directory for the links.  If no pathname is given, links will
 
     Specify the directory for the links.  If no pathname is given, links will
Line 30: Line 91:
 
     WARNING: ALL symlinks within the destination directory and its
 
     WARNING: ALL symlinks within the destination directory and its
 
     subdirectories (recursive) will be removed.
 
     subdirectories (recursive) will be removed.
 +
  
 
--chanid chanid
 
--chanid chanid
Line 198: Line 260:
  
 
==Perl prerequisites==
 
==Perl prerequisites==
'''mythrename.pl''' requires the Perl modules:
+
'''mythlink.pl''' requires the Perl modules:
 
* <code>Net::UPnP::QueryResponse</code>
 
* <code>Net::UPnP::QueryResponse</code>
 
* <code>Net::UPnP::ControlPoint</code>.
 
* <code>Net::UPnP::ControlPoint</code>.
  
{{Note box:You should only do the following "manual" install if your distro does not provide a package for the modules.}}
+
{{Note box|You should only do the following "manual" install if your distro does not provide a package for the modules.}}
  
 
In Gentoo and other Linux distros you can install these by running "cpan" at a terminal, most likely as root. Answer the prompts that follow, then type
 
In Gentoo and other Linux distros you can install these by running "cpan" at a terminal, most likely as root. Answer the prompts that follow, then type
 
  install Net::UPnP::ControlPoint
 
  install Net::UPnP::ControlPoint
 
  install Net::UPnP::QueryResponse
 
  install Net::UPnP::QueryResponse
then run mythrename.pl either as a user with proper user:group permissions at a terminal or use the same command shown below as a "job" under mythtv-setup.
+
then run mythlink.pl either as a user with proper user:group permissions at a terminal or use the same command shown below as a "job" under mythtv-setup.
 +
 
  
 
==Location==
 
==Location==
Line 213: Line 276:
 
mythlink.pl is a contributed script. Various distro file locations are below:
 
mythlink.pl is a contributed script. Various distro file locations are below:
  
* Ubuntu 10.04:
+
* Ubuntu 10.04, 12.04, 14.04:
 
** /usr/share/doc/mythtv-backend/contrib/user_jobs/mythlink.pl
 
** /usr/share/doc/mythtv-backend/contrib/user_jobs/mythlink.pl
  
Line 221: Line 284:
  
 
  mythlink.pl --rename
 
  mythlink.pl --rename
 +
 +
If creating a cron job entry to run mythlink.pl at regular intervals you may need to use a back slash to quote the % symbols if using the format option
 +
 +
e.g. */5 * * * * /usr/local/bin/mythlink.pl --link /media/nas/tvtmp --format \%T/\%Y\%m\%d:\%H\%i
 +
 +
==Errors==
 +
 +
If you get this error: "Unable to connect to mythbackend, is it running?" check the following file:
 +
 +
.mythtv/config.xml, and you need to ensure the following has a value (Mythbuntu 14.04.1 does not): <LocalHostName>my-unique-identifier-goes-here</LocalHostName>
 +
 +
[[Category:Perl Scripts]]
 +
[[Category:User_Job_Scripts]]
 +
[[Category:MythTV_System_Event_Scripts]]

Latest revision as of 19:34, 20 May 2023


Author Chris Peterson
Description Creates symlinks to local recordings from a user defined
Supports Version23.png  Version24.png  Version25.png  Version26.png Version27.png 


mythlink.pl is a Perl script (written by Chris Peterson) for creating human-readable symlinks to MythTV recordings. Once you have created a directory of readable symlinks, the show can be archived with the link's name using appropriate copy or move commands.

Whilst support for 0.26 and 0.27 is indicated above, a note from the developers (May 2014): "The Python bindings are the best way to create new scripts for MythTV, but no one has rewritten mythlink.pl functionality using the Python bindings (and doing so probably doesn't offer much of any benefit over the still-functional mythlink.pl), so it's still the best way to get user-friendly file-system views of your recordings. "

Usage

Database and directory settings are automatically detected, so usage is as simple as:

mythlink.pl --link [destination directory]

In the event that [destination directory] exists, mythlink.pl will first delete all symlinks underneath that directory and then begin creating new symlinks. This will remove symlinks to recordings that have since been deleted.

Note that when specifying --filename or --chanid and --starttime, deletion of old symlinks is suppressed. Therefore, anyone using this script in a user job or with the event system should still run the script occasionally without the --filename or --chanid and --starttime arguments to allow removal of links that referred to recordings since deleted. Alternatively, you may use a script triggered on "Recording deleted" and "Recording expired" to remove the specific link when its recording is removed.

See mythlink.pl --help (as below) for more information.

Examples

mythlink.pl --link /mnt/pretty --format '%T/%T%-%S'

creates links using the format [title]/[title]-[subtitle]

mythlink.pl --link /mnt/pretty --format '%Y%m%d-%H%i-%eH%ei-%T-%S'

creates links using the format [startdate]-[starttime]-[endtime]-[title]-[subtitle]

mythlink.pl --link /mnt/pretty --format '%T/%Y%m%d-%H%i-%eH%ei-%S'

creates links using the format [title]/[startdate]-[starttime]-[endtime]-[subtitle]

mythlink.pl --link /mnt/pretty --format '%U-%T-%Y%m%d-%H%i-%eH%ei-%S'

creates links using the format [recgroup]-[title]-[startdate]-[starttime]-[endtime]-[subtitle]

mythlink.pl --link /mnt/pretty --format '%C-%T-%Y%m%d-%H%i-%eH%ei-%S'

creates links using the format [category]-[title]-[startdate]-[starttime]-[endtime]-[subtitle]

mythlink.pl --link /mnt/pretty --format '%T-%oY%om%od-%S'

creates links using the format [title]-[original airdate]-[subtitle]


Using as a User Job

When used as a User Job, mythlink.pl will be executed when the recording ends, and can be configured such that it only creates a link for the new recording. To use the script as a User Job, specify the --chanid and --starttime arguments in addition to any other desired arguments and it will create a link only for the new recording:

mythlink.pl --link /mnt/pretty --chanid "%CHANID%" --starttime "%STARTTIMEUTC%"  --format '%T/%T%-%S'

Important.png Note: You will also need to run mythlink.pl separately to remove old symlinks. See Usage.

Using with MythTV System Events

When using the script with MythTV System Events, mythlink.pl can be executed as soon as the recording begins, using the Recording started event. To use the script with MythTV System Events, specify the --chanid and --starttime arguments in addition to any other desired arguments, and it will create a link only for the new recording:

mythlink.pl --link /mnt/pretty --chanid "%CHANID%" --starttime "%STARTTIMEUTC%"  --format '%T/%T%-%S'

Users with a relatively slow storage device (eg on a nas drive) have found it necessary to delay starting mythlink.pl:

sleep 10 && mythlink.pl --link /mnt/pretty --chanid "%CHANID%" --starttime "%STARTTIMEUTC%"  --format '%T/%T%-%S'


Important.png Note: You will also need to run mythlink.pl separately to remove old symlinks. See Usage.

Help Output

mythlink.pl usage:

options:

--link [destination directory]
--dest [destination directory]
--destination [destination directory]
--path [destination directory]

    (This option can be given as --link, --dest, --destination or --path.
    All of these alternatives produce the same behaviour.)

    Specify the directory for the links.  If no pathname is given, links will
    be created in the show_names directory inside of the current mythtv data
    directory on this machine.  eg:

    /var/video/show_names/

    WARNING: ALL symlinks within the destination directory and its
    subdirectories (recursive) will be removed.


--chanid chanid

    Create a link only for the specified recording file. Use with --starttime
    to specify a recording. This argument may be used with the event-driven
    notification system's "Recording started" event or in a post-recording
    user job.

--starttime starttime

    Create a link only for the specified recording file. Use with --chanid
    to specify a recording. This argument may be used with the event-driven
    notification system's "Recording started" event or in a post-recording
    user job.

--filename absolute_filename

    Create a link only for the specified recording file. This argument may be
    used with the event-driven notification system's "Recording started" event
    or in a post-recording user job.

--live

    Include live tv recordings.

    default: do not link live tv recordings

--format

    default:  %T %- %Y-%m-%d, %g-%i %A %- %S

    %T   = Title (show name)
    %S   = Subtitle (episode name)
    %R   = Description
    %C   = Category
    %U   = RecGroup
    %hn  = Hostname of the machine where the file resides
    %c   = Channel:  MythTV chanid
    %cn  = Channel:  channum
    %cc  = Channel:  callsign
    %cN  = Channel:  channel name
    %y   = Recording start time:  year, 2 digits
    %Y   = Recording start time:  year, 4 digits
    %n   = Recording start time:  month
    %m   = Recording start time:  month, leading zero
    %j   = Recording start time:  day of month
    %d   = Recording start time:  day of month, leading zero
    %g   = Recording start time:  12-hour hour
    %G   = Recording start time:  24-hour hour
    %h   = Recording start time:  12-hour hour, with leading zero
    %H   = Recording start time:  24-hour hour, with leading zero
    %i   = Recording start time:  minutes
    %s   = Recording start time:  seconds
    %a   = Recording start time:  am/pm
    %A   = Recording start time:  AM/PM
    %ey  = Recording end time:  year, 2 digits
    %eY  = Recording end time:  year, 4 digits
    %en  = Recording end time:  month
    %em  = Recording end time:  month, leading zero
    %ej  = Recording end time:  day of month
    %ed  = Recording end time:  day of month, leading zero
    %eg  = Recording end time:  12-hour hour
    %eG  = Recording end time:  24-hour hour
    %eh  = Recording end time:  12-hour hour, with leading zero
    %eH  = Recording end time:  24-hour hour, with leading zero
    %ei  = Recording end time:  minutes
    %es  = Recording end time:  seconds
    %ea  = Recording end time:  am/pm
    %eA  = Recording end time:  AM/PM
    %py  = Program start time:  year, 2 digits
    %pY  = Program start time:  year, 4 digits
    %pn  = Program start time:  month
    %pm  = Program start time:  month, leading zero
    %pj  = Program start time:  day of month
    %pd  = Program start time:  day of month, leading zero
    %pg  = Program start time:  12-hour hour
    %pG  = Program start time:  24-hour hour
    %ph  = Program start time:  12-hour hour, with leading zero
    %pH  = Program start time:  24-hour hour, with leading zero
    %pi  = Program start time:  minutes
    %ps  = Program start time:  seconds
    %pa  = Program start time:  am/pm
    %pA  = Program start time:  AM/PM
    %pey = Program end time:  year, 2 digits
    %peY = Program end time:  year, 4 digits
    %pen = Program end time:  month
    %pem = Program end time:  month, leading zero
    %pej = Program end time:  day of month
    %ped = Program end time:  day of month, leading zero
    %peg = Program end time:  12-hour hour
    %peG = Program end time:  24-hour hour
    %peh = Program end time:  12-hour hour, with leading zero
    %peH = Program end time:  24-hour hour, with leading zero
    %pei = Program end time:  minutes
    %pes = Program end time:  seconds
    %pea = Program end time:  am/pm
    %peA = Program end time:  AM/PM
    %oy  = Original Airdate:  year, 2 digits
    %oY  = Original Airdate:  year, 4 digits
    %on  = Original Airdate:  month
    %om  = Original Airdate:  month, leading zero
    %oj  = Original Airdate:  day of month
    %od  = Original Airdate:  day of month, leading zero
    %%   = a literal % character

    * The program start time is the time from the listings data and is not
      affected by when the recording started.  Therefore, using program start
      (or end) times may result in duplicate names.  In that case, the script
      will append a "counter" value to the name.

    * A suffix of .mpg or .nuv will be added where appropriate.

    * To separate links into subdirectories, include the / format specifier
      between the appropriate fields.  For example, "%T/%S" would create
      a directory for each title containing links for each recording named
      by subtitle.  You may use any number of subdirectories in your format
      specifier.

--separator

    The string used to separate sections of the link name.  Specifying the
    separator allows trailing separators to be removed from the link name and
    multiple separators caused by missing data to be consolidated. Indicate the
    separator character in the format string using either a literal character
    or the %- specifier.

    default:  '-'

--replacement

    Characters in the link name which are not legal on some filesystems will
    be replaced with the given character

    illegal characters:  \ : * ? < > | "

    default:  '-'

--underscores

    Replace whitespace in filenames with underscore characters.

    default:  No underscores

--rename

    Rename the recording files back to their default names.  If you had
    previously used mythrename.pl to rename files (rather than creating links
    to the files), use this option to restore the file names to their default
    format.

    Renaming the recording files is no longer supported.  Instead, use
    http://www.mythtv.org/wiki/mythfs.py to create a FUSE file system that
    represents recordings using human-readable file names or use mythlink.pl to
    create links with human-readable names to the recording files.

--verbose

    Print debug info.

    default:  No info printed to console

--help

    Show this help text.

Perl prerequisites

mythlink.pl requires the Perl modules:

  • Net::UPnP::QueryResponse
  • Net::UPnP::ControlPoint.


Important.png Note: You should only do the following "manual" install if your distro does not provide a package for the modules.

In Gentoo and other Linux distros you can install these by running "cpan" at a terminal, most likely as root. Answer the prompts that follow, then type

install Net::UPnP::ControlPoint
install Net::UPnP::QueryResponse

then run mythlink.pl either as a user with proper user:group permissions at a terminal or use the same command shown below as a "job" under mythtv-setup.


Location

mythlink.pl is a contributed script. Various distro file locations are below:

  • Ubuntu 10.04, 12.04, 14.04:
    • /usr/share/doc/mythtv-backend/contrib/user_jobs/mythlink.pl

Tips

If you have previously run the mythrename.pl command and changed your recording file names, you should change them back using:

mythlink.pl --rename

If creating a cron job entry to run mythlink.pl at regular intervals you may need to use a back slash to quote the % symbols if using the format option

e.g. */5 * * * * /usr/local/bin/mythlink.pl --link /media/nas/tvtmp --format \%T/\%Y\%m\%d:\%H\%i

Errors

If you get this error: "Unable to connect to mythbackend, is it running?" check the following file:

.mythtv/config.xml, and you need to ensure the following has a value (Mythbuntu 14.04.1 does not): <LocalHostName>my-unique-identifier-goes-here</LocalHostName>