« back to all changes in this revision
Viewing changes to mythtvfs.pod
- browse files at revision 8
- compare with another revision
- download diff
- download tarball
- view history from revision 8
- Committer: Kees Cook
- Date: 2009-03-12 20:16:58 UTC
- Revision ID: kees@outflux.net-20090312201658-1kjxja8ydrhkfw45
Tags: 0.5.1
version 0.5.1
- files added:
- mythtvfs.pod
- files modified:
- AUTHORS
added
removed
mythtvfs.pod
1
=head1 NAME
2
3
mythtvfs - a FUSE filesystem for accessing and managing MythTV
4
recordings
5
6
=head1 SYNOPSIS
7
8
mythtvfs [-h|--help]
9
mythtvfs [-V|--version]
10
mythtvfs [options] -o host=BACKEND ORIGPATH MOUNT
11
12
C<BACKEND> is the hostname of the MythTV backend system
13
14
C<ORIGPATH> is the path to MythTV's recordings directory
15
16
C<MOUNT> is a location to mount the new FUSE filesystem
17
mythtvfs will establish.
18
19
Options:
20
21
-h, --help prints a help message and exits
22
-V, --version prints the version and exits
23
-d, -o debug enable debug output (implies -f)
24
-f foreground operation
25
-s disable multi-threaded operation
26
-o host=HOST MythTV backend hostname
27
-o port=PORT MythTV backend port number
28
-o short-display shorter filename display format
29
-o logfile=FILE write verbose logging to FILE
30
-o backend-version=N force a specific backend version
31
-o program-width=N force a specific backend program width
32
-o <option[=value]> passes FUSE-specific options to the FUSE system
33
34
=head1 DESCRIPTION
35
36
B<mythtvfs> is a "filesystem in userspace" (FUSE) interface to the
37
MythTV Personal Video Recorder (PVR) software, that allows you to
38
interact with mythtv as if it were a file system. It creates an overlay
39
filesystem that encodes recording metadata (title, episode, description,
40
etc.) into a filename so that systems that do not natively talk to
41
MythTV can still get information about a given show. This allows use of
42
standard UNIX programs (ls, grep, cut, sort) to search and select
43
programs, and permits running video software like mplayer directly from
44
the command line rather than via the normal MythTV GUI frontend.
45
46
The value of this is that it enables scripting of MythTV interactions
47
using any scripting language, through standard file system type
48
operations. Examples could include: a bash script for grepping through
49
the listings to find a show and play it with mplayer; a Perl script to
50
encode and copy episodes of your favorite television shows onto a video
51
iPod; a Python script that downsamples/compresses recordings of a given
52
tv series more than a month old to save disk space; a Ruby program to
53
generate an alternate GUI interface to list available recordings and
54
allow playing them via mplayer.
55
56
This may also be useful for users wishing to access mythtv and play
57
recordings from systems that cannot run mythtv (such as if they're
58
running different Linux distros).
59
60
A design goal is to provide compatibility with the in-filename metadata
61
extraction capabilities in Galleon. See Filename Structure below.
62
63
=head2 Usage
64
65
After installing the FUSE libraries and kernel modules, mythtvfs can be
66
built using the standard `./configure && make`.
67
68
Unless your MythTV backend is running locally, you will also need to
69
enable NFS on the backend, export the MythTV video repository (typically
70
/var/lib/mythtv) and establish an NFS mount locally (at, say,
71
/srv/myth).
72
73
MythTVfs can then be started from the command line as root:
74
75
mythtvfs -o host=mythtv.my.network /srv/myth/recordings /media/mythtvfs
76
77
or you can mount mythtvfs via fstab, for example:
78
79
mythtvfs#/media/mythtvfs /srv/myth/recordings fuse noauto,host=mythtv.my.network 0 0
80
81
See EXAMPLES below for more alternatives.
82
83
84
=head2 Filename Structure
85
86
Filenames in the MythTVfs filesystem are named based on their TV
87
Program's metadata. The elements are contained by the brace symbols
88
("{}") and have the original filename embedded, and then end with
89
".mpg".
90
91
{SERIES_TITLE}{AIR_DATE}{EPISODE_TITLE}{RECORD_DATE}{CHANNEL}{DURATION}{DESCRIPTION}FILE.mpg
92
93
Where "RECORD_DATE" has the format "07.15 PM Wed Mar 31, 2005", and
94
"AIR_DATE" has the format "2005-03-31". "DURATION" is measured in
95
seconds, and "CHANNEL" is the shortened channel "callsign". "FILE" is
96
the original MythTV filename for storage
97
(e.g. "1013_20051207210000_20051207220000.nuv"). The file ends with
98
".mpg" because Galleon will only recognize file extensions that it
99
expects the TiVo to be able to play.
100
101
102
=head2 Hooking to Galleon
103
104
You'll need a version of Galleon that understands this file format
105
layout. A patch against 2.1.0 is available on the MythTVfs homepage.
106
Just add a "GoBack" path that matches your MythTVfs mount point, and it
107
will automatically extract all the metadata from the filename.
108
109
110
=head1 OPTIONS
111
112
=over 8
113
114
=item B<-h>, B<--help>
115
116
Prints a synopsis of program usage and exits.
117
118
=item B<-V>, B<--version>
119
120
Prints the program version and exits.
121
122
=item B<-d>, B<-o debug>
123
124
Enable debug output (implies -f)
125
126
=item B<-f>
127
128
Foreground operation
129
130
=item B<-s>
131
132
disable multi-threaded operation
133
134
=item B<-o> B<option>[=I<value>]
135
136
-o host=HOST MythTV backend hostname
137
138
-o port=PORT MythTV backend port number
139
140
-o short-display shorter filename display format
141
142
-o logfile=FILE write verbose logging to FILE
143
144
-o backend-version=N force a specific backend version
145
146
-o program-width=N force a specific backend program width
147
148
Other options passed directly to the FUSE system:
149
150
-o allow_other allow access to other users
151
152
-o allow_root allow access to root
153
154
-o nonempty allow mounts over non-empty file/dir
155
156
-o default_permissions enable permission checking by kernel
157
158
-o fsname=NAME set filesystem name
159
160
-o subtype=NAME set filesystem type
161
162
-o large_read issue large read requests (2.4 only)
163
164
-o max_read=N set maximum size of read requests
165
166
-o hard_remove immediate removal (don't hide files)
167
168
-o use_ino let filesystem set inode numbers
169
170
-o readdir_ino try to fill in d_ino in readdir
171
172
-o direct_io use direct I/O
173
174
-o kernel_cache cache files in kernel
175
176
-o [no]auto_cache enable caching based on modification times
177
178
-o umask=M set file permissions (octal)
179
180
-o uid=N set file owner
181
182
-o gid=N set file group
183
184
-o entry_timeout=T cache timeout for names (1.0s)
185
186
-o negative_timeout=T cache timeout for deleted names (0.0s)
187
188
-o attr_timeout=T cache timeout for attributes (1.0s)
189
190
-o ac_attr_timeout=T auto cache timeout for attributes (attr_timeout)
191
192
-o intr allow requests to be interrupted
193
194
-o intr_signal=NUM signal to send on interrupt (10)
195
196
-o modules=M1[:M2...] names of modules to push onto filesystem stack
197
198
-o max_write=N set maximum size of write requests
199
200
-o max_readahead=N set maximum readahead
201
202
-o async_read perform reads asynchronously (default)
203
204
-o sync_read perform reads synchronously
205
206
-o subdir=DIR prepend this directory to all paths
207
208
-o [no]rellinks transform absolute symlinks to relative
209
210
-o from_code=CHARSET original encoding of file names (default: UTF-8)
211
212
-o to_code=CHARSET new encoding of the file names (default: ANSI_X3.4-1968)
213
214
=head1 EXAMPLES
215
216
=head2 Filesystem Mount Examples
217
218
To create a /media/mythtvfs on a local MythTV system (both backend and
219
frontend are on the same system)
220
221
mythtvfs -o host=localhost /var/lib/mythtv/recordings /media/mythtvfs
222
223
For mounting against a remote host named 'sparky', with its mythtv dir
224
NFS mounted locally at /myth, you might do:
225
226
mythtvfs -o allow_other,host=sparky /myth/recordings /media/mythtvfs
227
228
229
=head2 Command Line Use
230
231
Show a listing of all recorded titles and number of episodes for each:
232
233
# ls | cut -d} -f 1 | sed -e "s/{//" | uniq -c
234
235
23 Dark Angel
236
7 Nature
237
4 Survivorman
238
26 The Colbert Report
239
42 The Daily Show With Jon Stewart
240
241
Listing Nature programs sorted by original air date with newest first:
242
243
# ls {Nature}* | cut -d} -f 2,3 | sed -e "s/{//g" | sed -e "s/}/ /g" | sort -r
244
245
2007-11-11 The Cheetah Orphans
246
2007-11-04 In the Valley of the Wolves
247
2007-10-28 Silence of the Bees
248
2007-02-11 Supersize Crocs
249
2005-02-13 From Orphan to King
250
2005-01-09 Violent Hawaii
251
2004-02-08 Diamonds
252
253
Play the oldest episode of Dark Angel by original air date:
254
255
# ls {Dark\ Angel}* | cut -d} -f 2,8 | sort -r | \
256
sed -e "s/.*\}\(.*\)\.mpg$/\1/" | head -1 | xargs mplayer
257
258
259
=head1 SEE ALSO
260
261
L<http://outflux.net/software/pkgs/mythtvfs-fuse/>
262
263
=head1 ERRORS
264
265
=head2 No listings in /media/mythtvfs, but files present in /myth/recordings
266
267
Check that the mythtv system's mysql process is running.
268
269
=head2 "myhost: Connection timed out"
270
271
Doublecheck that the second argument to mythtvfs is a valid hostname
272
that is network accessible. Try running `ping myhost`.
273
274
=head2 "fuse: bad mount point `/media/mythtvfs': Transport endpoint is not connected"
275
276
Something appears to have killed the mythtvfs process or mythtvfs has
277
otherwise died (perhaps due to a bug you should report?) rendering its
278
mount point unavailable. Try umount'ing the mount point, killing the
279
mythtvfs process (if it's hung), and re-establishing the mythtvfs
280
process. In the worst case, it may be required to reboot the system to
281
get things back to normal.
282
283
=head2 "umount: /media/mythtvfs: device is busy"
284
285
A process is still accessing the mythtvfs file system, preventing it
286
from being unmounted. Try running `lsof | grep mythtvfs` to find
287
processes that may have open file handles in the file system.
288
289
290
=head1 BUGS
291
292
Please report bugs directly to the author.
293
294
295
=head1 HISTORY
296
297
B<mythtvfs> was written initially with the motivation to connect mythtv
298
into Galleon.
299
300
301
=head1 COPYRIGHT AND LICENSE
302
303
B<Copyright (C)> 2005-2008 by Kees Cook
304
305
B<mythtvfs> is free software; you can redistribute it and/or modify it
306
under the terms of the GPL.
307
308
Manpage B<Copyright (C)> 2007 by Bryce Harrington (licensed under the same
309
terms as mythtvfs itself).
310
Loggerhead is a web-based interface for Breezy
Version: 2.0.1