917 lines
30 KiB
Groff
917 lines
30 KiB
Groff
.\" This manpage has been automatically generated by docbook2man
|
|
.\" from a DocBook document. This tool can be found at:
|
|
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
|
|
.\" Please send any bug reports, improvements, comments, patches,
|
|
.\" etc. to Steve Cheng <steve@ggi-project.org>.
|
|
.TH "HPODDER" "1" "27 April 2010" "John Goerzen"
|
|
|
|
.SH NAME
|
|
hpodder \- Scan and download podcasts
|
|
.SH SYNOPSIS
|
|
|
|
\fBhpodder\fR [ \fB-d\fR ] [ \fB\fIcommand\fB\fR ] [ \fB\fIcommand_args\fB\fR ]
|
|
|
|
.SH "DESCRIPTION"
|
|
|
|
.PP
|
|
Podcasting
|
|
is a method of publishing radio-like programs on the
|
|
Internet. Through podcasting, almost anyone can produce their
|
|
own audio program, and publish episodes of it as often or as
|
|
rarely as they like.
|
|
.PP
|
|
To listen to podcasts, you need a program to download the
|
|
podcast's episodes from the Internet. Such a program is
|
|
called a podcatcher (or sometimes a podcast aggregator).
|
|
\fBhpodder\fR is this program.
|
|
.PP
|
|
If you'd like to get going RIGHT NOW, skip on down to the
|
|
Quick Start section. Otherwise, let's take a look at the
|
|
features of \fBhpodder\fR\&.
|
|
.SS "FEATURE LIST"
|
|
.TP 0.2i
|
|
\(bu
|
|
Convenient, easy to learn, and fast command-line
|
|
interface (it's simple to do simple things, and
|
|
advanced things are possible)
|
|
.TP 0.2i
|
|
\(bu
|
|
Automatic discovery of feed metadata such as title
|
|
.TP 0.2i
|
|
\(bu
|
|
Full history database for accurate
|
|
prevention of duplicate downloads and tracking of new episodes
|
|
.TP 0.2i
|
|
\(bu
|
|
Conversion tools to convert your existing
|
|
feed list and history from other applications to
|
|
\fBhpodder\fR\&. Supported applications and formats include:
|
|
castpodder and ipodder.
|
|
.TP 0.2i
|
|
\(bu
|
|
Most operations can work fully automatically
|
|
across your entire podcast database, or they can work
|
|
manually as well.
|
|
.TP 0.2i
|
|
\(bu
|
|
Automatic updating of ID3 (v1 and v2) tags
|
|
based on metadata in the podcast itself. This important
|
|
feature is available through iTunes but is often missed by
|
|
other podcatchers.
|
|
.TP 0.2i
|
|
\(bu
|
|
\fBhpodder\fR operations can be easily scripted
|
|
or scheduled using regular operating system tools.
|
|
.TP 0.2i
|
|
\(bu
|
|
Fully customizable naming scheme for
|
|
downloaded episodes, including a name collision detection
|
|
and workaround algorithm.
|
|
.TP 0.2i
|
|
\(bu
|
|
Automatic support for appending .mp3
|
|
extensions to MP3 files that lack it.
|
|
.TP 0.2i
|
|
\(bu
|
|
Numerous database and history inquiry tools
|
|
.TP 0.2i
|
|
\(bu
|
|
Small, minimalist footprint
|
|
.TP 0.2i
|
|
\(bu
|
|
Power users and developers can interact
|
|
directly with the embedded Sqlite3 database used by
|
|
\fBhpodder\fR\&. The database has a simple schema that is
|
|
developer-friendly.
|
|
.TP 0.2i
|
|
\(bu
|
|
Support for resuming interrupted downloads
|
|
of podcasts
|
|
.TP 0.2i
|
|
\(bu
|
|
\fBhpodder\fR is SAFE and is designed with data
|
|
integrity in mind from the beginning. It should be
|
|
exceedingly difficult to lose a podcast episode, even in the
|
|
event of a power failure.
|
|
.SS "METHOD OF OPERATION"
|
|
.PP
|
|
The basic pattern of operation with \fBhpodder\fR is to set up
|
|
each podcast you want to receive. Each day (or hour, or
|
|
whatever), \fBhpodder\fR will go out and update its database by
|
|
pulling in the latest episode lists from the podcast feed.
|
|
Then, \fBhpodder\fR will proceed to download any episodes that
|
|
you haven't already downloaded. After each episode is
|
|
downloaded, \fBhpodder\fR will note that fact so it isn't ever
|
|
downloaded again.
|
|
.PP
|
|
Let's look at this in a bit more detail.
|
|
.PP
|
|
\fBhpodder\fR maintains two tables in a database. One table
|
|
lists all the podcasts you know about, as well as where the
|
|
podcast's feed is to be downloaded from. The feed is a file
|
|
that the podcast's author publishes. It lists all the
|
|
current episodes of the podcast, and some information about
|
|
them. Data is added to this table with the \fBhpodder
|
|
add\fR command.
|
|
.PP
|
|
The second table lists each episode for a given podcast,
|
|
along with the location from which the episode can be
|
|
downloaded and some other information about the episode
|
|
(such as its title). Information in this table is added by
|
|
\fBhpodder update\fR and updated by
|
|
\fBhpodder download\fR or
|
|
\fBhpodder catchup\fR\&.
|
|
.PP
|
|
When you first fire up \fBhpodder\fR, it will read its
|
|
configuration file from
|
|
\fI~/.hpodder/hpodder.conf\fR\&.
|
|
What happens next depends on the command.
|
|
.PP
|
|
For \fBhpodder update\fR, the program will read
|
|
information about all your podcasts. It will download each
|
|
feed. Once it has the feed, it will look at each episode
|
|
and compare them to the database. If a given episode is
|
|
already in the database, it is ignored. Any new episodes
|
|
are recorded in the database, and set to Pending so they
|
|
will be downloaded on the next download run.
|
|
.PP
|
|
For \fBhpodder download\fR, the program will
|
|
read information about all your episodes. For each episode
|
|
marked Pending, the program will download the episode. It
|
|
will then update the episode's ID3 tags based on the podcast
|
|
feed. Finally, it will move the episode in-place
|
|
atomically. Only after all that has been done will
|
|
\fBhpodder\fR mark the episode as Downloaded in the database.
|
|
In this way, no episode is visible to outside tools until it
|
|
is completely downloaded in its final form, so you can
|
|
safely play any visible program in your download directory
|
|
even as downloads are happening.
|
|
.SH "QUICK START"
|
|
.PP
|
|
This section will describe how a first-time \fBhpodder\fR user can
|
|
get up and running quickly. It assumes you already have
|
|
\fBhpodder\fR compiled or installed on your system. If not,
|
|
please follow the instructions in the
|
|
\fIINSTALL\fR
|
|
file in the
|
|
source distribution.
|
|
.PP
|
|
To get started, simply run \fBhpodder\fR at your
|
|
shell prompt. \fBhpodder\fR will lead you through the first-time
|
|
configuration -- which is only two questions and completely
|
|
self-explanatory!
|
|
.PP
|
|
After this, whenever you want to download the latest episodes
|
|
for your podcast, just run \fBhpodder\fR again.
|
|
.PP
|
|
At some point, you'll want to add more podcasts to \fBhpodder\fR\&.
|
|
To do that, just run a command such as:
|
|
.PP
|
|
\fBhpodder add
|
|
\fIhttp://www.example.com/feed.xml\fB\fR
|
|
.PP
|
|
Just replace the example.com URL here with the real URL of the
|
|
feed you want to add. Then run \fBhpodder
|
|
update\fR\&. If the podcast you've just added has a
|
|
whole bunch of episodes, you may not want to download them
|
|
all. In that case, run \fBhpodder catchup
|
|
\fIid\fB\fR, where
|
|
\fIid\fR is the podcast number that
|
|
\fBhpodder\fR gave your new podcast when you added it.
|
|
.PP
|
|
Again, from here on, you can just run
|
|
\fBhpodder\fR to download all your new episodes.
|
|
.SH "OPTIONS"
|
|
.PP
|
|
\fBhpodder\fR always is invoked with the name of a specific
|
|
operation, such as \fBupdate\fR or
|
|
\fBadd\fR\&. In \fBhpodder\fR, these operations are
|
|
called \fBcommands\fR\&. Each command has its
|
|
own options, which are given after the command on the
|
|
\fBhpodder\fR command line. A full summary of each command's
|
|
options is given later in this manual.
|
|
.PP
|
|
You may obtain a list of all commands with \fBhpodder
|
|
lscommands\fR\&. Help is available for any individual
|
|
command with \fBhpodder \fIcommand\fB
|
|
--help\fR\&. Global help is available with
|
|
\fBhpodder --help\fR\&.
|
|
.SS "GLOBAL OPTION"
|
|
.PP
|
|
This option may be specified \fBbefore\fR any
|
|
command.
|
|
.TP
|
|
\fB-d\fR
|
|
.TP
|
|
\fB--debug\fR
|
|
Enables debugging output. This verbose output helps you
|
|
learn what \fBhpodder\fR is doing every step of the way and
|
|
diagnose any problems you may encounter.
|
|
.SH "COMMANDS IN HPODDER"
|
|
.PP
|
|
\fBhpodder\fR has many different commands. If you do not specify a
|
|
command, the \fBfetch\fR command is automatically
|
|
selected for you. This section will discuss each command in
|
|
detail. Note that all commands are case-sensitive and should be
|
|
\fBgiven in lowercase\fR\&.
|
|
.PP
|
|
All commands support the command \fB--help\fR\&. Running
|
|
\fBhpodder \fIcommand\fB
|
|
--help\fR will display information about the command and
|
|
its options. Since all commands support this, it won't be
|
|
explicitly listed for each command below.
|
|
.SS "ADD"
|
|
|
|
\fBhpodder add\fR \fB\fIURL\fB\fR
|
|
|
|
.PP
|
|
This command is used to add a new podcast to \fBhpodder\fR\&. You
|
|
can must provide the URL (link) to the podcast you want to add
|
|
to this command. For example:
|
|
.PP
|
|
\fBhpodder add
|
|
http://feeds.feedburner.com/Bsdtalk\fR
|
|
.PP
|
|
A podcast can be later removed with \fBhpodder
|
|
rm\fR\&. You can adjust its URL later with
|
|
\fBhpodder mv\fR\&.
|
|
.SS "CATCHUP"
|
|
|
|
\fBhpodder catchup\fR [ \fB-n \fInumber\fB\fR ] [ \fB\fIcastid\fB\fR\fI ...\fR ]
|
|
|
|
.PP
|
|
Running \fBcatchup\fR will cause \fBhpodder\fR to
|
|
mark all but the most recent episodes as Skipped. This will
|
|
prevent \fBhpodder\fR from automatically downloading such
|
|
episodes.
|
|
.TP
|
|
\fB-n \fINUM\fB\fR
|
|
.TP
|
|
\fB--number-eps=\fINUM\fB\fR
|
|
By default, only the single most recent episode is exempted
|
|
from being "caught up". If you want to exclude more
|
|
episodes from being "caught up" -- and thus allow more
|
|
to be downloaded -- use this option to allow more
|
|
episodes to remain downloadable.
|
|
.TP
|
|
\fB\fIcastid ...\fB\fR
|
|
By default, this command will operate on all podcasts. You can limit the podcasts on which it operates with this option. See specifying podcast IDs later in this manual for more information.
|
|
.SS "DISABLE"
|
|
|
|
\fBhpodder disable\fR \fBcastid\fR\fI ...\fR
|
|
|
|
.PP
|
|
This command will flag podcasts as disabled. Podcasts flagged
|
|
disabled will be skipped during an \fBupdate\fR,
|
|
\fBdownload\fR, or \fBfetch\fR\&.
|
|
They will still participate with all other commands.
|
|
\fBhpodder lscasts\fR will notify you of which
|
|
podcasts are disabled.
|
|
.PP
|
|
This can be useful if you want to stop following a podcast for
|
|
awhile, but think you may want to come back to it in the
|
|
future. The podcast URL and your download history will remain
|
|
in the \fBhpodder\fR database, unlike with \fBhpodder
|
|
rm\fR\&.
|
|
.PP
|
|
Disabled podcasts can be re-enabled with \fBhpodder
|
|
enable\fR\&.
|
|
.PP
|
|
One or more podcast IDs are required; see the section below on
|
|
specifying podcast IDs for more details.
|
|
.SS "DOWNLOAD"
|
|
|
|
\fBhpodder download\fR [ \fB\fIcastid\fB\fR\fI ...\fR ]
|
|
|
|
.PP
|
|
The \fBdownload\fR command is used to actually
|
|
perform the download of podcasts to your system. By default,
|
|
\fBdownload\fR will download all available
|
|
episodes. You can, however, specify only certain podcasts to
|
|
process; if you do, all available episodes for only those
|
|
podcasts will be downloaded.
|
|
.TP
|
|
\fB\fIcastid ...\fB\fR
|
|
By default, this command will operate on all podcasts. You can limit the podcasts on which it operates with this option. See specifying podcast IDs later in this manual for more information.
|
|
.SS "ENABLE"
|
|
|
|
\fBhpodder enable\fR \fBcastid\fR\fI ...\fR
|
|
|
|
.PP
|
|
This command will flag podcasts as enabled. This is the
|
|
default state. See \fBhpodder disable\fR for
|
|
information on manually disabling podcasts and what it means
|
|
to be disabled.
|
|
.PP
|
|
One or more podcast IDs are required; see the section below on
|
|
specifying podcast IDs for more details.
|
|
.SS "FETCH"
|
|
|
|
\fBhpodder fetch\fR [ \fB\fIcastid\fB\fR\fI ...\fR ]
|
|
|
|
.PP
|
|
The \fBfetch\fR is the main worker command for
|
|
\fBhpodder\fR\&. It is simply equivolent to \fBhpodder
|
|
update\fR followed by \fBhpodder
|
|
download\fR\&. That is, it will scan all podcasts for
|
|
new episodes, then download any pending episodes.
|
|
.PP
|
|
This command is the default command if no command is given on
|
|
the \fBhpodder\fR command line.
|
|
.PP
|
|
As a special feature, the first time that
|
|
\fBfetch\fR is invoked, it will execute the new
|
|
user setup procedure.
|
|
.TP
|
|
\fB\fIcastid ...\fB\fR
|
|
By default, this command will operate on all podcasts. You can limit the podcasts on which it operates with this option. See specifying podcast IDs later in this manual for more information.
|
|
.SS "IMPORT-IPODDER"
|
|
|
|
\fBhpodder import-ipodder\fR [ \fB--from=\fIPATH\fB\fR ]
|
|
|
|
.PP
|
|
With this command, \fBhpodder\fR can import both your podcast list
|
|
and your download history from ipodder or CastPodder.
|
|
\fBhpodder\fR will import all podcasts referenced there, with the
|
|
exception that any podcasts that are already in \fBhpodder\fR\&'s
|
|
database will be entirely untouched.
|
|
.TP
|
|
\fB--from=\fIPATH\fB\fR
|
|
By default, \fBhpodder\fR will look for the ipodder
|
|
database in the \fI\&.ipodder\fR directory in
|
|
the user's home directory. This may not always be correct:
|
|
for instance, on non-Unix platforms or when using
|
|
CastPodder, this directory will be different. With this
|
|
option, you can tell \fBhpodder\fR where to find the
|
|
ipodder/CastPodder database.
|
|
.SS "LSCASTS"
|
|
|
|
\fBhpodder lscasts\fR [ \fB-l\fR ]
|
|
|
|
.PP
|
|
This command will display all podcasts that are configured
|
|
within \fBhpodder\fR\&. For each podcast, you will see the podcast
|
|
ID, the number of pending downloads, the total number of
|
|
episodes ever seen by \fBhpodder\fR, and the title of the podcast.
|
|
.TP
|
|
\fB-l\fR
|
|
If you add the \fB-l\fR option, then
|
|
\fBlscasts\fR will also display the feed URL
|
|
for each podcast.
|
|
.SS "LSCOMMANDS"
|
|
|
|
\fBhpodder lscommands\fR
|
|
|
|
.PP
|
|
This command will display a list of all available \fBhpodder\fR
|
|
commands along with a brief description of each.
|
|
.SS "LSEPISODES / LSEPS"
|
|
|
|
\fBhpodder lsepisodes\fR [ \fB-l\fR ] [ \fB\fIcastid\fB\fR\fI ...\fR ]
|
|
|
|
|
|
\fBhpodder lseps\fR [ \fB-l\fR ] [ \fB\fIcastid\fB\fR\fI ...\fR ]
|
|
|
|
.PP
|
|
The \fBlsepisodes\fR command will display a list
|
|
of every episode known to \fBhpodder\fR\&. The output will include
|
|
the ID of the podcast to which the episode belongs, the
|
|
episode ID, the status of the episode, and the title of the
|
|
episode.
|
|
.PP
|
|
\fBlseps\fR is simply an alias for
|
|
\fBlsepisodes\fR and performs in the same manner.
|
|
.TP
|
|
\fB-l\fR
|
|
If you add the \fB-l\fR option, then
|
|
\fBlsepisodes\fR includes the download URL for
|
|
each episode in its output.
|
|
.TP
|
|
\fB\fIcastid ...\fB\fR
|
|
By default, this command will operate on all podcasts. You can limit the podcasts on which it operates with this option. See specifying podcast IDs later in this manual for more information.
|
|
.SS "RM"
|
|
|
|
\fBhpodder rm\fR \fBcastid\fR\fI ...\fR
|
|
|
|
.PP
|
|
This command will remove all knowledge about a given podcast
|
|
from hpodder, including all entries about that podcast in the
|
|
episode database.
|
|
.PP
|
|
One or more podcast IDs are required; see the section below on
|
|
specifying podcast IDs for more details. Unlike most other
|
|
\fBhpodder\fR commands that accept an empty podcast ID list to
|
|
mean all podcasts, \fBrm\fR does not because of
|
|
the destructive potential of such a request.
|
|
.SS "SETSTATUS"
|
|
|
|
\fBhpodder setstatus\fR \fB--castid=\fIID\fB\fR \fB--status=\fISTATUS\fB\fR \fBepid\fR\fI ...\fR
|
|
|
|
.PP
|
|
The \fBsetstatus\fR command is used to manually
|
|
adjust the status flags on individual episodes. You can use
|
|
it to flag individual episodes for downloading (or not).
|
|
.PP
|
|
You must specify at least one episode ID. \fBNote that
|
|
the plain IDs given to this command are episode IDs\fR, and not
|
|
podcast IDs like other commands.
|
|
.PP
|
|
Statuses are case-sensitive and must be given with a leading
|
|
uppercase letter and trailing lowercase letters. Available
|
|
status are given later in this manual.
|
|
.SS "SETTITLE"
|
|
|
|
\fBhpodder settitle\fR \fB--castid=\fIID\fB\fR \fB--title=\fITITLE\fB\fR
|
|
|
|
.PP
|
|
The \fBsettitle\fR is used to manually set the
|
|
title of a given podcast. Normally, \fBhpodder\fR will
|
|
automatically get the title from the podcast's XML feed.
|
|
Sometimes the XML feed for the podcast may not provide a
|
|
useful title. In those situations, you can use
|
|
\fBsettitle\fR to manually override the title.
|
|
.PP
|
|
Please note that if you want to set the title to a name that
|
|
contains spaces, you will need to quote it for the shell.
|
|
.SS "UPDATE"
|
|
|
|
\fBhpodder update\fR [ \fB\fIcastid\fB\fR\fI ...\fR ]
|
|
|
|
.PP
|
|
The update command will cause \fBhpodder\fR to look at each
|
|
podcast feed. It will download the latest copy of the feed
|
|
and compare the episodes mentioned in the feed to its internal
|
|
database of episodes. For any episode mentioned in the feed
|
|
that is not already in the internal database of episodes,
|
|
\fBhpodder\fR will add it to its database and set its status to
|
|
Pending.
|
|
.TP
|
|
\fB\fIcastid ...\fB\fR
|
|
By default, this command will operate on all podcasts. You can limit the podcasts on which it operates with this option. See specifying podcast IDs later in this manual for more information.
|
|
.SH "SPECIFYING PODCAST IDS"
|
|
|
|
.PP
|
|
Each podcast in \fBhpodder\fR gets a numeric ID. This ID is
|
|
automatically assigned by \fBhpodder\fR and is not changable. The
|
|
ID is given out when a podcast is added with the
|
|
\fBadd\fR command, or with the
|
|
\fBlscasts\fR or \fBlsepisodes\fR
|
|
commands.
|
|
.PP
|
|
The ID is designed as a constant way to refer to a particular
|
|
podcast. A podcast's title may change, or even its feed URL,
|
|
but the ID of a podcast will never change. It also is short and
|
|
easy to type on the command line.
|
|
.PP
|
|
Several commands can take a list of podcast IDs. If no IDs are
|
|
given, the commands will default to operating on all podcasts.
|
|
One or more IDs can be given, separated by spaces. If IDs are
|
|
given, then the commands will operate only on the podcasts with
|
|
the given IDs.
|
|
.PP
|
|
The special keyword \fBall\fR may be given, which
|
|
tells the system to operate on all podcasts. This yields the
|
|
same result as giving no IDs at all.
|
|
.SH "STATUS FLAGS IN HPODDER"
|
|
.PP
|
|
Several places in this manual, you've seen \fBhpodder\fR statuses
|
|
mentioned. Each episode in \fBhpodder\fR has an associated status.
|
|
The statuses are:
|
|
.TP
|
|
\fBPending\fR
|
|
The given episode is ready to
|
|
download
|
|
.TP
|
|
\fBDownloaded\fR
|
|
The given episode has already been
|
|
downloaded by \fBhpodder\fR
|
|
.TP
|
|
\fBError\fR
|
|
An error occured while downloading this
|
|
episode. It will not be downloaded again unless the flag is
|
|
set back to Pending.
|
|
.TP
|
|
\fBSkipped\fR
|
|
The user has requested that this episode not
|
|
be downloaded. Commands such as \fBcatchup\fR or
|
|
\fBimport-ipodder\fR could cause this.
|
|
.SH "AUTOMATIC ERROR HANDLING"
|
|
.PP
|
|
For whatever reason, podcast feeds or individual episodes sometimes
|
|
fail to download. The reasons for this range from the podcast being
|
|
taken down by its author to the network being disconnected from the
|
|
local computer.
|
|
.PP
|
|
People that track many podcasts over a long time will probably find it
|
|
annoying to have \fBhpodder\fR attempt to download invalid feeds or
|
|
episodes over and over again. For that reason, \fBhpodder\fR 1.0.0
|
|
introduced automatic error handling.
|
|
.PP
|
|
Once a podcast feed or episode has failed at least 15 times,
|
|
it's been at least 21 days since the first download attempt (episodes)
|
|
or last update (feeds), \fBhpodder\fR will automatically mark the item to
|
|
be skipped in future runs. For podcast feeds, \fBhpodder\fR disabled the
|
|
podcast; this status will appear in \fBhpodder lscasts\fR\&.
|
|
For episodes, \fBhpodder\fR sets the status to Error; this will appear
|
|
in \fBhpodder lseps\fR\&. Both can be changed later, with
|
|
\fBhpodder enable\fR or \fBhpodder setstatus\fR,
|
|
respectively.
|
|
.PP
|
|
The default minimums of 15 attempts and 21 days may be adjusted in
|
|
the \fBhpodder\fR configuration file, either globally or on a per-podcast
|
|
basis.
|
|
.PP
|
|
If you wish to disable checking entirely, you can put lines such as
|
|
epfaildays = 123456789 and
|
|
podcastfaildays = 123456789 in your DEFAULT
|
|
section in \fI~/.hpodder/hpodder.conf\fR\&. Of course, if you
|
|
have podcasts that still fail after 338,237 years, you could be in
|
|
trouble.
|
|
.SH "HPODDER CONFIGURATION FILE"
|
|
.PP
|
|
\fBhpodder\fR has a configuration file in which you can set various
|
|
options. This file normally lives under
|
|
\fI~/.hpodder/hpodder.conf\fR\&.
|
|
.PP
|
|
The configuration file has multiple sections. Each section has
|
|
a name and is introduced with the name in brackets. Each
|
|
section has one or more options.
|
|
.PP
|
|
The section named DEFAULT is special in that it provides
|
|
defaults that will be used whenever an option can't be found
|
|
under a different section.
|
|
.PP
|
|
Let's start by looking at an example file, and then proceed to
|
|
examine all the options that are available.
|
|
|
|
.nf
|
|
[DEFAULT]
|
|
|
|
; Most podcasts are downloaded to here
|
|
downloaddir = /home/jgoerzen/podcasts
|
|
|
|
namingpatt = %(safecasttitle)s/%(safefilename)s
|
|
|
|
; Don't disable a podcast due to errors unless it's been at least 20
|
|
; days since the last (or first) attempt
|
|
podcastfaildays = 20
|
|
|
|
[general]
|
|
|
|
; The following line tells hpodder that
|
|
; you have already gone through the intro.
|
|
showintro = no
|
|
|
|
maxthreads = 2
|
|
progressinterval = 1
|
|
|
|
[31]
|
|
; Store this particular podcast somewhere else
|
|
downloaddir = /nfs/remote/podcasts
|
|
|
|
; And we don't care as much about disabling it
|
|
podcastfaildays = 5
|
|
.fi
|
|
.PP
|
|
In this example, you saw some "general" options, such as
|
|
\fBshowintro\fR\&. There are two other sections
|
|
represented: \fB31\fR and \fBDEFAULT\fR\&.
|
|
.PP
|
|
Whenever \fBhpodder\fR looks for information about a particular
|
|
podcast, it first checks to see if it can find that option in a
|
|
section for that podcast. If not, it checks the
|
|
\fBDEFAULT\fR section. If it still doesn't find an
|
|
answer, it consults its built-in defaults.
|
|
.PP
|
|
In this example, all podcasts share the same naming scheme. All
|
|
podcasts except podcast 31 are downloaded to the same place.
|
|
That podcast goes elsewhere because its
|
|
\fBdownloaddir\fR overrides the default.
|
|
.SS "GENERAL OPTIONS"
|
|
.PP
|
|
These are specified in the \fBgeneral\fR
|
|
section.
|
|
.TP
|
|
\fBmaxthreads\fR
|
|
The maximum number of simultaneous download
|
|
threads that will be active at any given time.
|
|
\fBhpodder\fR can download multiple files at once, and this
|
|
options says how many it can download simultaneously.
|
|
It defaults to 2.
|
|
.TP
|
|
\fBprogressinterval\fR
|
|
How frequently to update the status bar on
|
|
the screen, in seconds. It defaults to 1, which will update
|
|
the status every second. Raise it if you are running
|
|
\fBhpodder\fR over a very low-bandwidth link and are concerned
|
|
about flooding it with status updates.
|
|
.TP
|
|
\fBshowintro\fR
|
|
The first time you run
|
|
\fBfetch\fR, \fBhpodder\fR automatically writes a
|
|
configuration file for you that sets this option to
|
|
\fBno\fR\&. This prevents you from having to
|
|
do the new user intro more than once.
|
|
.SS "PER-PODCAST OPTIONS"
|
|
.PP
|
|
These options may be specified in \fBDEFAULT\fR or
|
|
in a per-podcast section. If placed in
|
|
\fBDEFAULT\fR, they will apply to all podcasts
|
|
unless overridden.
|
|
.SS "BASIC PER-PODCAST OPTIONS"
|
|
.TP
|
|
\fBdownloaddir\fR
|
|
The main directory into which all podcasts
|
|
should be stored. It will be created by \fBhpodder\fR when
|
|
necessary if it does not already exist. The default is
|
|
\fI~/podcasts\fR
|
|
.TP
|
|
\fBepfailattempts\fR
|
|
The minimum number of attempts to download this episode before
|
|
the episode will be considered to be marked Error. Default is
|
|
15.
|
|
.TP
|
|
\fBepfaildays\fR
|
|
The minimum number of days that must have elapsed between the
|
|
first attempt to download the episode and the present time before
|
|
the episode will be considered to be marked Error. Default is
|
|
21.
|
|
.TP
|
|
\fBnamingpatt\fR
|
|
How to name downloaded files. This pattern
|
|
is relative to the \fBdownloaddir\fR\&. The
|
|
default is
|
|
\fI%(safecasttitle)s/%(safefilename)s\fR
|
|
|
|
This option will be provided with several replaceable
|
|
tokens. Tokens have the form
|
|
\fB%(\fItokname\fB)s\fR\&.
|
|
That is, the percent sign, the token name in
|
|
perenthesis, and then an "s" character. The tokens made
|
|
available for this option are:
|
|
.RS
|
|
.TP
|
|
\fBcastid\fR
|
|
The numeric ID for this
|
|
podcast
|
|
.TP
|
|
\fBepid\fR
|
|
The numeric ID for this
|
|
episode
|
|
.TP
|
|
\fBsafecasttitle\fR
|
|
The title of the podcast, as specified
|
|
in the feed. Special characters, such as spaces or
|
|
exclamation marks, are converted to
|
|
underscores.
|
|
.TP
|
|
\fBsafeeptitle\fR
|
|
The title of this episode, as
|
|
specified in the podcast's feed, with special
|
|
characters converted to underscores.
|
|
.TP
|
|
\fBsafefilename\fR
|
|
The component from the URL for this
|
|
episode after the last slash in the URL, with special
|
|
characters converted to underscores.
|
|
.RE
|
|
.TP
|
|
\fBpodcastfailattempts\fR
|
|
The minimum number of attempts to download this podcast before
|
|
the episode will be considered to be marked disabled. Default is
|
|
15.
|
|
.TP
|
|
\fBpodcastfaildays\fR
|
|
The minimum number of days that must have elapsed between the
|
|
last successful download of the podcast's feed
|
|
and the present time before
|
|
the podcast will be considered to be marked disabled. Default is
|
|
21.
|
|
.SS "PER-PODCAST COMMAND OPTIONS"
|
|
.PP
|
|
These are external commands that will be run in certain
|
|
situations. For each of the commands, several environment
|
|
variables are set. These variables are not pre-sanitized
|
|
and may contain whitespace or special characters.
|
|
\fBExtreme
|
|
caution must be exercized to properly quote these variables
|
|
when using them in shell commands or scripts.\fR
|
|
The following
|
|
environment variables are set:
|
|
.TP
|
|
\fBCASTID\fR
|
|
The numeric ID for this podcast
|
|
.TP
|
|
\fBCASTTITLE\fR
|
|
The title of the podcast,
|
|
verbatim
|
|
.TP
|
|
\fBEPFILENAME\fR
|
|
The on-disk filename where this episode
|
|
has been stored
|
|
.TP
|
|
\fBEPID\fR
|
|
The numeric epidose ID for this
|
|
episode
|
|
.TP
|
|
\fBEPTITLE\fR
|
|
The title of this episode, as specified in
|
|
the podcast's feed.
|
|
.TP
|
|
\fBEPURL\fR
|
|
The URL of this episode.
|
|
.TP
|
|
\fBFEEDURL\fR
|
|
The URL of the podcast's
|
|
feed.
|
|
.TP
|
|
\fBSAFECASTTITLE\fR
|
|
The title of the podcast, as specified in
|
|
the feed. Special characters, such as spaces or
|
|
exclamation marks, are converted to
|
|
underscores.
|
|
.TP
|
|
\fBSAFEEPTITLE\fR
|
|
The title of this episode, as specified in
|
|
the podcast's feed, with special characters converted to
|
|
underscores.
|
|
.PP
|
|
Here are the supported commands:
|
|
.TP
|
|
\fBgettypecommand\fR
|
|
This command is intended to analyze the
|
|
content of the file and return the true MIME type of the
|
|
file, based on the on-disk content. If this command exits
|
|
with an error, the MIME type given in the podcast feed will
|
|
be used. If you want to always use the MIME type in the
|
|
podcast feed, you can set this to
|
|
/bin/false or the empty string.
|
|
|
|
The default value is: file -b -i "${EPFILENAME}"
|
|
|
|
It is expected that this program will write its result
|
|
to standard output. The first token of the output is
|
|
taken to be the MIME type. The remainder will be
|
|
discarded. For instance, for the output
|
|
text/x-pascal; charset=us-ascii,
|
|
the type will be taken to be
|
|
text/x-pascal\&. If the program
|
|
exits with a nonzero exit code, its output will not be used.
|
|
.TP
|
|
\fBpostproccommand\fR
|
|
This command provides a user-configurable
|
|
post-processing hook for downloaded podcasts. It is only
|
|
invoked on files whose type matches the
|
|
\fBpostproctypes\fR list. This command is the
|
|
very last step in the downloading process.
|
|
|
|
The default value adds ID3 tags to MP3 files. It is:
|
|
mid3v2 -T "${EPID}" -A "${CASTTITLE}" -t "${EPTITLE}" --WOAF
|
|
"${EPURL}" --WOAS "${FEEDURL}" "${EPFILENAME}"
|
|
.SS "PER-PODCAST TYPE PROCESSING LISTS"
|
|
.PP
|
|
These options govern what types of files are processed in
|
|
different ways. The types used here are MIME types. They
|
|
will be the actual type determined by
|
|
\fBgettypecommand\fR, or if that command is
|
|
unable to determine a useful type, the MIME type given by
|
|
the podcast's RSS feed. Items in these lists are to be
|
|
separated by commas.
|
|
.TP
|
|
\fBpostproctypes\fR
|
|
This is the comma-separated list of MIME types on
|
|
which \fBpostproccommand\fR will operate.
|
|
The special single token ALL means
|
|
to operate on all types. To disable post-processing
|
|
entirely, you can set this to the empty string.
|
|
The default is: audio/mpeg, audio/mp3,
|
|
x-audio/mp3
|
|
.TP
|
|
\fBrenametypes\fR
|
|
This option governs the automatic renaming of
|
|
downloaded files. Some servers do not present files
|
|
with proper extensions to match their file type. This
|
|
can confuse various software and devices. \fBhpodder\fR
|
|
can automatically fix up extensions on such files.
|
|
Each entry in the list in a MIME type, a colon, and
|
|
the desired filename suffix. Note that no whitespace
|
|
is allowed around the colon.
|
|
|
|
The default is: audio/mpeg:.mp3,
|
|
audio/mp3:.mp3, x-audio/mp3:.mp3
|
|
.SH "CURL CONFIGURATION FILE"
|
|
.PP
|
|
Internally, \fBhpodder\fR uses the Curl application to perform
|
|
downloads across the Internet. Curl is a remarkably flexible
|
|
application, and \fBhpodder\fR takes advantage of that to provide
|
|
you with quite a few options.
|
|
.PP
|
|
You can customize Curl as much as you like by creating a Curl
|
|
configuration file in \fI~/.hpodder/curlrc\fR\&.
|
|
Please see \fBcurl\fR(1) for more details
|
|
on the content of that file.
|
|
.PP
|
|
Some things you can do with this file include restricting
|
|
the maximum download rate, suppressing or adjusting the progress
|
|
meter, configuring proxies, etc.
|
|
.SH "TIPS & HINTS"
|
|
.PP
|
|
Here are a few tips and hints to make \fBhpodder\fR more pleasant
|
|
for you.
|
|
.SS "GOING THROUGH A PROXY"
|
|
|
|
.PP
|
|
If your connections must go through a proxy, you have two
|
|
options: set an environment varilable or configure the proxy
|
|
in your \fI~/.hpodder/curlrc\fR\&. If you use an
|
|
environment variable, your settings will also impact other
|
|
applications -- and that's probably what you want. See the
|
|
Environment section later for tips on doing that.
|
|
.SS "LIMITING YOUR DOWNLOAD SPEED"
|
|
|
|
.PP
|
|
Sometimes, you may not want \fBhpodder\fR to use all of your
|
|
available bandwidth. Perhaps you don't want it to slow down
|
|
other activities too much. To do this, just create a
|
|
\fI~/.hpodder/curlrc\fR file. Put in it
|
|
something like this:
|
|
|
|
.nf
|
|
limit-rate=20k
|
|
.fi
|
|
.PP
|
|
This will limit the download rate to 20 KB/sec.
|
|
.PP
|
|
This rate limitation is imperfect and may not do well during
|
|
\fBupdate\fR, but it should do exactly what you
|
|
want during \fBdownload\fR\&.
|
|
.SH "ENVIRONMENT"
|
|
|
|
.PP
|
|
\fBhpodder\fR does not read any environment variables directly.
|
|
However, it does pass on the environment to the
|
|
programs it calls, such as Curl. This can be useful for
|
|
specifying proxies. Please see
|
|
\fBcurl\fR(1) for more details.
|
|
As specified in the Per-Podcast Command Options section, \fBhpodder\fR
|
|
will also set certain variables for post-processing of
|
|
downloaded files.
|
|
.SH "CONFORMING TO"
|
|
.TP 0.2i
|
|
\(bu
|
|
The Extensible Markup Language
|
|
(XML) <URL:http://www.w3.org/XML/> standard (W3C)
|
|
.TP 0.2i
|
|
\(bu
|
|
RSS 2.0 <URL:http://blogs.law.harvard.edu/tech/rss>
|
|
(Harvard Law)
|
|
.TP 0.2i
|
|
\(bu
|
|
HTTP 1.1, FTP, plus SSL/TLS and any other
|
|
protocols supported by Curl
|
|
.TP 0.2i
|
|
\(bu
|
|
ID3 v1 and v2
|
|
.SH "COPYRIGHT"
|
|
|
|
.PP
|
|
\fBhpodder\fR, all code, documentation, files, and build scripts are
|
|
Copyright (C) 2006 John Goerzen. All code, documentation,
|
|
sripts, and files are under the following license unless
|
|
otherwise noted:
|
|
.PP
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or
|
|
(at your option) any later version.
|
|
.PP
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
.PP
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program; if not, write to the Free Software
|
|
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
|
.PP
|
|
The GNU General Public License is available in the file COPYING
|
|
in the source distribution. Debian GNU/Linux users may find this in
|
|
/usr/share/common-licenses/GPL-2.
|
|
.PP
|
|
If the GPL is unacceptable for your uses, please e-mail me; alternative
|
|
terms can be negotiated for your project.
|
|
.SH "AUTHOR"
|
|
.PP
|
|
\fBhpodder\fR, its modules, documentation, executables, and all
|
|
included files, except where noted, was written by
|
|
John Goerzen <jgoerzen@complete.org> and
|
|
copyright is held as stated in the COPYRIGHT section.
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
\fBcurl\fR(1),
|
|
\fBmid3v2\fR(1)
|
|
.PP
|
|
The \fBhpodder\fR homepage at <URL:http://software.complete.org/hpodder>,
|
|
a general description of podcasting at
|
|
<URL:http://en.wikipedia.org/wiki/Podcast>
|