.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MYTHTVFS 1" .TH MYTHTVFS 1 "2011-11-23" "0.6.1" "MythTVFS Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" mythtvfs \- a FUSE filesystem for accessing and managing MythTV recordings .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& mythtvfs [\-h|\-\-help] \& mythtvfs [\-V|\-\-version] \& mythtvfs [options] \-o host=BACKEND ORIGPATH MOUNT .Ve .PP \&\f(CW\*(C`BACKEND\*(C'\fR is the hostname of the MythTV backend system .PP \&\f(CW\*(C`ORIGPATH\*(C'\fR is the path to MythTV's recordings directory .PP \&\f(CW\*(C`MOUNT\*(C'\fR is a location to mount the new \s-1FUSE\s0 filesystem mythtvfs will establish. .PP Options: .PP .Vb 10 \& \-h, \-\-help prints a help message and exits \& \-V, \-\-version prints the version and exits \& \-d, \-o debug enable debug output (implies \-f) \& \-f foreground operation \& \-s disable multi\-threaded operation \& \-o host=HOST MythTV backend hostname \& \-o port=PORT MythTV backend port number \& \-o format=FORMAT format to use for filename \& \-o date_format=FORMAT format to use for date fields (i.e. airdate) \& \-o datetime_format=S format to use for date+time fields (i.e. start) \& \-o short\-display shorter filename display format \& \-o logfile=FILE write verbose logging to FILE \& \-o backend\-version=N force a specific backend version \& \-o program\-width=N force a specific backend program width \& \-o invalid\-chars=STR list of characters not allowed in filenames \& \-o replacement\-char=C character to replace invalid characters with \& \-o passes FUSE\-specific options to the FUSE system .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBmythtvfs\fR is a \*(L"filesystem in userspace\*(R" (\s-1FUSE\s0) interface to the MythTV Personal Video Recorder (\s-1PVR\s0) software, that allows you to interact with mythtv as if it were a file system. It creates an overlay filesystem that encodes recording metadata (title, episode, description, etc.) into a filename so that systems that do not natively talk to MythTV can still get information about a given show. This allows use of standard \s-1UNIX\s0 programs (ls, grep, cut, sort) to search and select programs, and permits running video software like mplayer directly from the command line rather than via the normal MythTV \s-1GUI\s0 frontend. .PP The value of this is that it enables scripting of MythTV interactions using any scripting language, through standard file system type operations. Examples could include: a bash script for grepping through the listings to find a show and play it with mplayer; a Perl script to encode and copy episodes of your favorite television shows onto a video iPod; a Python script that downsamples/compresses recordings of a given tv series more than a month old to save disk space; a Ruby program to generate an alternate \s-1GUI\s0 interface to list available recordings and allow playing them via mplayer. .PP This may also be useful for users wishing to access mythtv and play recordings from systems that cannot run mythtv (such as if they're running different Linux distros). .PP A design goal is to provide compatibility with the in-filename metadata extraction capabilities in Galleon. See Filename Structure below. .SS "Usage" .IX Subsection "Usage" After installing the \s-1FUSE\s0 libraries and kernel modules, mythtvfs can be built using the standard `./configure && make`. .PP Unless your MythTV backend is running locally, you will also need to enable \s-1NFS\s0 on the backend, export the MythTV video repository (typically /var/lib/mythtv) and establish an \s-1NFS\s0 mount locally (at, say, /srv/myth). .PP MythTVfs can then be started from the command line as root: .PP .Vb 1 \& mythtvfs \-o host=mythtv.my.network /srv/myth/recordings /media/mythtvfs .Ve .PP or you can mount mythtvfs via fstab, for example: .PP .Vb 1 \& mythtvfs#/media/mythtvfs /srv/myth/recordings fuse noauto,host=mythtv.my.network 0 0 .Ve .PP See \s-1EXAMPLES\s0 below for more alternatives. .SS "Filename Structure" .IX Subsection "Filename Structure" Filenames in the MythTVfs filesystem default to being named based on their \s-1TV\s0 Program's metadata. The elements are contained by the brace symbols (\*(L"{}\*(R") and have the original filename embedded, and then end with \&\*(L".mpg\*(R". .PP {\s-1SERIES_TITLE\s0}{\s-1AIRED\s0}{\s-1EP_TITLE\s0}{\s-1REC_DATE\s0}{\s-1CHAN\s0}{\s-1DURATION\s0}{\s-1DESC\s0}FILE.mpg .PP Where \*(L"\s-1REC_DATE\*(R"\s0 has the format \*(L"Sat Jan 24 22:58:00 2009\*(R", and \&\*(L"\s-1AIRED\*(R"\s0 has the format \*(L"2005\-03\-31\*(R". \*(L"\s-1DURATION\*(R"\s0 is measured in seconds, and \*(L"\s-1CHAN\*(R"\s0 is the shortened channel \*(L"callsign\*(R". \*(L"\s-1FILE\*(R"\s0 is the original MythTV filename for storage (e.g. \*(L"1013_20051207210000_20051207220000.nuv\*(R"). The file ends with \&\*(L".mpg\*(R" because Galleon will only recognize file extensions that it expects the TiVo to be able to play. .PP If you dislike the default filename format, you can change it using the \*(L"format\*(R" option. .SS "Hooking to Galleon" .IX Subsection "Hooking to Galleon" You'll need a version of Galleon that understands this file format layout. A patch against 2.1.0 is available on the MythTVfs homepage. Just add a \*(L"GoBack\*(R" path that matches your MythTVfs mount point, and it will automatically extract all the metadata from the filename. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-h\fR, \fB\-\-help\fR" 8 .IX Item "-h, --help" Prints a synopsis of program usage and exits. .IP "\fB\-V\fR, \fB\-\-version\fR" 8 .IX Item "-V, --version" Prints the program version and exits. .IP "\fB\-d\fR, \fB\-o debug\fR" 8 .IX Item "-d, -o debug" Enable debug output (implies \-f) .IP "\fB\-f\fR" 8 .IX Item "-f" Foreground operation .IP "\fB\-s\fR" 8 .IX Item "-s" disable multi-threaded operation .IP "\fB\-o\fR \fBoption\fR[=\fIvalue\fR]" 8 .IX Item "-o option[=value]" \&\-o host=HOST MythTV backend hostname .Sp \&\-o port=PORT MythTV backend port number .Sp \&\-o format=FORMAT Format to use for filenames. Defaults to \&\*(L"{%T}{%a}{%S}{%s}{%c}{%d}{%D}%f.mpg\*(R". See below for what the various tags mean. .Sp \&\-o date_format=S Format to use within date fields, i.e. airdate. These tags follow \fIstrftime\fR\|(1) rules. .Sp \&\-o datetime_format=S Format to use within date+time fields, i.e. start. These tags follow \fIstrftime\fR\|(1) rules. .Sp \&\-o short-display shorter filename display format. Equivalent to setting format=\*(L"{%T}{%a}{%S}{%s}{%c}{%d}%f.mpg\*(R", except for a slight change in the internal format of \f(CW%s\fR. .Sp \&\-o logfile=FILE write verbose logging to \s-1FILE\s0 .Sp \&\-o backend\-version=N force a specific backend version .Sp \&\-o program\-width=N force a specific backend program width .Sp \&\-o invalid\-chars=STR list of characters not allowed in filenames .Sp \&\-o replacement\-char=C character to replace invalid characters with .Sp Other options passed directly to the \s-1FUSE\s0 system: .Sp \&\-o allow_other allow access to other users .Sp \&\-o allow_root allow access to root .Sp \&\-o nonempty allow mounts over non-empty file/dir .Sp \&\-o default_permissions enable permission checking by kernel .Sp \&\-o fsname=NAME set filesystem name .Sp \&\-o subtype=NAME set filesystem type .Sp \&\-o large_read issue large read requests (2.4 only) .Sp \&\-o max_read=N set maximum size of read requests .Sp \&\-o hard_remove immediate removal (don't hide files) .Sp \&\-o use_ino let filesystem set inode numbers .Sp \&\-o readdir_ino try to fill in d_ino in readdir .Sp \&\-o direct_io use direct I/O .Sp \&\-o kernel_cache cache files in kernel .Sp \&\-o [no]auto_cache enable caching based on modification times .Sp \&\-o umask=M set file permissions (octal) .Sp \&\-o uid=N set file owner .Sp \&\-o gid=N set file group .Sp \&\-o entry_timeout=T cache timeout for names (1.0s) .Sp \&\-o negative_timeout=T cache timeout for deleted names (0.0s) .Sp \&\-o attr_timeout=T cache timeout for attributes (1.0s) .Sp \&\-o ac_attr_timeout=T auto cache timeout for attributes (attr_timeout) .Sp \&\-o intr allow requests to be interrupted .Sp \&\-o intr_signal=NUM signal to send on interrupt (10) .Sp \&\-o modules=M1[:M2...] names of modules to push onto filesystem stack .Sp \&\-o max_write=N set maximum size of write requests .Sp \&\-o max_readahead=N set maximum readahead .Sp \&\-o async_read perform reads asynchronously (default) .Sp \&\-o sync_read perform reads synchronously .Sp \&\-o subdir=DIR prepend this directory to all paths .Sp \&\-o [no]rellinks transform absolute symlinks to relative .Sp \&\-o from_code=CHARSET original encoding of file names (default: \s-1UTF\-8\s0) .Sp \&\-o to_code=CHARSET new encoding of the file names (default: \s-1ANSI_X3.4\-1968\s0) .SS "Format tags" .IX Subsection "Format tags" The following format tags are undersood: .PP \&\f(CW%a\fR Airdate, e.g. \*(L"1961\-11\-17\*(R", defined by \-o date_format .PP \&\f(CW%c\fR Station callsign, e.g. \*(L"\s-1SCIFI\*(R"\s0 .PP \&\f(CW%D\fR Show description, e.g. \*(L"The Earth begins moving closer to the sun.\*(R" .PP \&\f(CW%d\fR Show duration in seconds, e.g. \*(L"1800\*(R" .PP \&\f(CW%f\fR mythtv file basename, e.g. \*(L"1029_20090201053000.mpg\*(R". .PP \&\f(CW%S\fR Show subtitle, e.g. \*(L"The Midnight Sun\*(R" .PP \&\f(CW%s\fR Start time, e.g. \*(L"05.30 \s-1AM\s0 Sun Feb 01, 2009\*(R", defined by \-o datetime_format .PP \&\f(CW%T\fR Show title, e.g. \*(L"The Twilight Zone\*(R" .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "Filesystem Mount Examples" .IX Subsection "Filesystem Mount Examples" To create a /media/mythtvfs on a local MythTV system (both backend and frontend are on the same system) .PP .Vb 1 \& mythtvfs \-o host=localhost /var/lib/mythtv/recordings /media/mythtvfs .Ve .PP For mounting against a remote host named 'sparky', with its mythtv dir \&\s-1NFS\s0 mounted locally at /myth, you might do: .PP .Vb 1 \& mythtvfs \-o allow_other,host=sparky /myth/recordings /media/mythtvfs .Ve .PP If you prefer a different file name format: .PP .Vb 1 \& mythtvfs \-o host=localhost,format="%T \- %S \- %s.mpg" /myth /mythtvfs .Ve .SS "Command Line Use" .IX Subsection "Command Line Use" Show a listing of all recorded titles and number of episodes for each: .PP # ls | cut \-d} \-f 1 | sed \-e \*(L"s/{//\*(R" | uniq \-c .PP .Vb 5 \& 23 Dark Angel \& 7 Nature \& 4 Survivorman \& 26 The Colbert Report \& 42 The Daily Show With Jon Stewart .Ve .PP Listing Nature programs sorted by original air date with newest first: .PP # ls {Nature}* | cut \-d} \-f 2,3 | sed \-e \*(L"s/{//g\*(R" | sed \-e \*(L"s/}/ /g\*(R" | sort \-r .PP .Vb 7 \& 2007\-11\-11 The Cheetah Orphans \& 2007\-11\-04 In the Valley of the Wolves \& 2007\-10\-28 Silence of the Bees \& 2007\-02\-11 Supersize Crocs \& 2005\-02\-13 From Orphan to King \& 2005\-01\-09 Violent Hawaii \& 2004\-02\-08 Diamonds .Ve .PP Play the oldest episode of Dark Angel by original air date: .PP # ls {Dark\e Angel}* | cut \-d} \-f 2,8 | sort \-r | \e sed \-e \*(L"s/.*\e}\e(.*\e)\e.mpg$/\e1/\*(R" | head \-1 | xargs mplayer .SH "SEE ALSO" .IX Header "SEE ALSO" .SH "ERRORS" .IX Header "ERRORS" .SS "No listings in /media/mythtvfs, but files present in /myth/recordings" .IX Subsection "No listings in /media/mythtvfs, but files present in /myth/recordings" Check that the mythtv system's mysql process is running. .ie n .SS """myhost: Connection timed out""" .el .SS "``myhost: Connection timed out''" .IX Subsection "myhost: Connection timed out" Doublecheck that the second argument to mythtvfs is a valid hostname that is network accessible. Try running `ping myhost`. .ie n .SS """fuse: bad mount point `/media/mythtvfs': Transport endpoint is not connected""" .el .SS "``fuse: bad mount point `/media/mythtvfs': Transport endpoint is not connected''" .IX Subsection "fuse: bad mount point `/media/mythtvfs': Transport endpoint is not connected" Something appears to have killed the mythtvfs process or mythtvfs has otherwise died (perhaps due to a bug you should report?) rendering its mount point unavailable. Try umount'ing the mount point, killing the mythtvfs process (if it's hung), and re-establishing the mythtvfs process. In the worst case, it may be required to reboot the system to get things back to normal. .ie n .SS """umount: /media/mythtvfs: device is busy""" .el .SS "``umount: /media/mythtvfs: device is busy''" .IX Subsection "umount: /media/mythtvfs: device is busy" A process is still accessing the mythtvfs file system, preventing it from being unmounted. Try running `lsof | grep mythtvfs` to find processes that may have open file handles in the file system. .SH "BUGS" .IX Header "BUGS" Please report bugs directly to the author. .SH "HISTORY" .IX Header "HISTORY" \&\fBmythtvfs\fR was written initially with the motivation to connect mythtv into Galleon. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" \&\fBCopyright (C)\fR 2005\-2008 by Kees Cook .PP \&\fBmythtvfs\fR is free software; you can redistribute it and/or modify it under the terms of the \s-1GPL.\s0 .PP Manpage \fBCopyright (C)\fR 2007 by Bryce Harrington (licensed under the same terms as mythtvfs itself). .PP Format support based on work by Morty Abzug, and licensed under the same terms as mythtvfs itself.