Provided by: hpodder_1.1.5.0+nmu3_i386 bug


       hpodder - Scan and download podcasts


       hpodder [ -d ] [ command ] [ command_args ]


       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

       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).  hpodder is this program.

       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 hpodder.

       · Convenient,  easy  to  learn,  and  fast command-line interface (it's
         simple to do simple things, and advanced things are possible)

       · Automatic discovery of feed metadata such as title

       · Full history database for accurate prevention of duplicate  downloads
         and tracking of new episodes

       · Conversion  tools to convert your existing feed list and history from
         other applications to hpodder.  Supported  applications  and  formats
         include: castpodder and ipodder.

       · Most  operations  can  work  fully  automatically  across your entire
         podcast database, or they can work manually as well.

       · 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.

       · hpodder operations can be easily scripted or scheduled using  regular
         operating system tools.

       · Fully customizable naming scheme for downloaded episodes, including a
         name collision detection and workaround algorithm.

       · Automatic support for appending .mp3 extensions  to  MP3  files  that
         lack it.

       · Numerous database and history inquiry tools

       · Small, minimalist footprint

       · Power  users  and  developers can interact directly with the embedded
         Sqlite3 database used by hpodder.  The database has a  simple  schema
         that is developer-friendly.

       · Support for resuming interrupted downloads of podcasts

       · hpodder  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.

       The  basic  pattern of operation with hpodder is to set up each podcast
       you want to receive.  Each day (or hour, or whatever), hpodder will  go
       out and update its database by pulling in the latest episode lists from
       the podcast feed.  Then, hpodder will proceed to download any  episodes
       that you haven't already downloaded.  After each episode is downloaded,
       hpodder will note that fact so it isn't ever downloaded again.

       Let's look at this in a bit more detail.

       hpodder 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  hpodder
       add command.

       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 hpodder update and updated  by  hpodder  download  or
       hpodder catchup.

       When  you  first  fire  up hpodder, it will read its configuration file
       from  ~/.hpodder/hpodder.conf.   What  happens  next  depends  on   the

       For  hpodder  update,  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.

       For hpodder download, 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  hpodder  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.


       This section will describe how a first-time hpodder user can get up and
       running  quickly.   It  assumes  you  already  have hpodder compiled or
       installed on your system.  If not, please follow  the  instructions  in
       the INSTALL file in the source distribution.

       To  get started, simply run hpodder at your shell prompt.  hpodder will
       lead you through the first-time configuration  --  which  is  only  two
       questions and completely self-explanatory!

       After  this, whenever you want to download the latest episodes for your
       podcast, just run hpodder again.

       At some point, you'll want to add more  podcasts  to  hpodder.   To  do
       that, just run a command such as:

       hpodder add

       Just replace the URL here with the real URL of the feed you
       want to add.  Then run hpodder update.   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 hpodder catchup id, where  id  is  the  podcast
       number that hpodder gave your new podcast when you added it.

       Again,  from here on, you can just run hpodder to download all your new


       hpodder always is invoked with the name of a specific  operation,  such
       as  update  or  add.  In hpodder, these operations are called commands.
       Each command has its own options, which are given after the command  on
       the  hpodder command line.  A full summary of each command's options is
       given later in this manual.

       You may obtain a list of all commands with hpodder lscommands.  Help is
       available  for  any  individual  command  with  hpodder command --help.
       Global help is available with hpodder --help.

       This option may be specified before any command.


              Enables debugging output.  This verbose output helps  you  learn
              what  hpodder  is  doing  every step of the way and diagnose any
              problems you may encounter.


       hpodder has many different commands.  If you do not specify a  command,
       the fetch command is automatically selected for you.  This section will
       discuss each command in detail.   Note  that  all  commands  are  case-
       sensitive and should be given in lowercase.

       All  commands  support  the  command  --help.   Running hpodder command
       --help will display information about  the  command  and  its  options.
       Since all commands support this, it won't be explicitly listed for each
       command below.

       hpodder add URL

       This command is used to add a new podcast to  hpodder.   You  can  must
       provide  the URL (link) to the podcast you want to add to this command.
       For example:

       hpodder add

       A podcast can be later removed with hpodder rm.  You can adjust its URL
       later with hpodder mv.

       hpodder catchup [ -n number ] [ castid ... ]

       Running  catchup  will  cause  hpodder  to mark all but the most recent
       episodes as Skipped.  This  will  prevent  hpodder  from  automatically
       downloading such episodes.

       -n NUM

              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.

       castid ...
              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

       hpodder disable castid ...

       This command will flag podcasts as disabled.  Podcasts flagged disabled
       will be skipped during an update, download, or fetch.  They will  still
       participate  with  all other commands.  hpodder lscasts will notify you
       of which podcasts are disabled.

       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  hpodder  database,
       unlike with hpodder rm.

       Disabled podcasts can be re-enabled with hpodder enable.

       One  or  more  podcast  IDs  are  required;  see  the  section below on
       specifying podcast IDs for more details.

       hpodder download [ castid ... ]

       The download command is  used  to  actually  perform  the  download  of
       podcasts  to  your  system.   By  default,  download  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.

       castid ...
              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

       hpodder enable castid ...

       This command will flag podcasts as enabled.  This is the default state.
       See hpodder disable for information on manually disabling podcasts  and
       what it means to be disabled.

       One  or  more  podcast  IDs  are  required;  see  the  section below on
       specifying podcast IDs for more details.

       hpodder fetch [ castid ... ]

       The fetch is the  main  worker  command  for  hpodder.   It  is  simply
       equivolent to hpodder update followed by hpodder download.  That is, it
       will scan all podcasts for new  episodes,  then  download  any  pending

       This  command  is  the  default  command  if no command is given on the
       hpodder command line.

       As a special feature, the first time that fetch  is  invoked,  it  will
       execute the new user setup procedure.

       castid ...
              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

       hpodder import-ipodder [ --from=PATH ]

       With this command, hpodder can import both your podcast list  and  your
       download  history  from ipodder or CastPodder.  hpodder will import all
       podcasts referenced there, with the exception that  any  podcasts  that
       are already in hpodder's database will be entirely untouched.

              By  default,  hpodder  will look for the ipodder database in the
              .ipodder 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   hpodder   where   to   find   the
              ipodder/CastPodder database.

       hpodder lscasts [ -l ]

       This command will display  all  podcasts  that  are  configured  within
       hpodder.   For each podcast, you will see the podcast ID, the number of
       pending downloads, the total number of episodes ever seen  by  hpodder,
       and the title of the podcast.

       -l     If  you  add  the  -l option, then lscasts will also display the
              feed URL for each podcast.

       hpodder lscommands

       This command will display a list  of  all  available  hpodder  commands
       along with a brief description of each.

       hpodder lsepisodes [ -l ] [ castid ... ]

       hpodder lseps [ -l ] [ castid ... ]

       The  lsepisodes  command  will display a list of every episode known to
       hpodder.  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.

       lseps is simply an alias  for  lsepisodes  and  performs  in  the  same

       -l     If  you add the -l option, then lsepisodes includes the download
              URL for each episode in its output.

       castid ...
              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

       hpodder rm castid ...

       This  command  will  remove  all  knowledge  about a given podcast from
       hpodder, including all  entries  about  that  podcast  in  the  episode

       One  or  more  podcast  IDs  are  required;  see  the  section below on
       specifying podcast IDs for more details.   Unlike  most  other  hpodder
       commands  that accept an empty podcast ID list to mean all podcasts, rm
       does not because of the destructive potential of such a request.

       hpodder setstatus --castid=ID --status=STATUS epid ...

       The setstatus command is used to manually adjust the  status  flags  on
       individual  episodes.   You  can use it to flag individual episodes for
       downloading (or not).

       You must specify at least one episode ID.   Note  that  the  plain  IDs
       given  to  this command are episode IDs, and not podcast IDs like other

       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.

       hpodder settitle --castid=ID --title=TITLE

       The settitle is used to manually set the  title  of  a  given  podcast.
       Normally,  hpodder  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 settitle to manually
       override the title.

       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.

       hpodder update [ castid ... ]

       The update command will cause hpodder 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, hpodder will add it to its database and set its
       status to Pending.

       castid ...
              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


       Each  podcast  in  hpodder gets a numeric ID.  This ID is automatically
       assigned by hpodder and is not changable.  The ID is given out  when  a
       podcast  is  added  with  the  add  command,  or  with  the  lscasts or
       lsepisodes commands.

       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.

       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.

       The special keyword all may be given, which tells the system to operate
       on all podcasts.  This yields the same result as giving no IDs at all.


       Several  places in this manual, you've seen hpodder statuses mentioned.
       Each episode in hpodder has an associated status.  The statuses are:

              The given episode is ready to download

              The given episode has already been downloaded by hpodder

       Error  An error occured while downloading this episode.  It will not be
              downloaded again unless the flag is set back to Pending.

              The  user  has  requested  that  this episode not be downloaded.
              Commands such as catchup or import-ipodder could cause this.


       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.

       People  that track many podcasts over a long time will probably find it
       annoying to have hpodder attempt to download invalid feeds or  episodes
       over  and  over  again.   For  that  reason,  hpodder  1.0.0 introduced
       automatic error handling.

       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), hpodder will automatically mark the item to be  skipped
       in  future runs.  For podcast feeds, hpodder disabled the podcast; this
       status will appear in hpodder lscasts.  For episodes, hpodder sets  the
       status  to  Error;  this  will  appear  in  hpodder lseps.  Both can be
       changed later, with hpodder enable or hpodder setstatus, respectively.

       The default minimums of 15 attempts and 21 days may be adjusted in  the
       hpodder configuration file, either globally or on a per-podcast basis.

       If  you  wish  to  disable checking entirely, you can put lines such as
       epfaildays = 123456789 and podcastfaildays = 123456789 in your  DEFAULT
       section  in  ~/.hpodder/hpodder.conf.   Of course, if you have podcasts
       that still fail after 338,237 years, you could be in trouble.


       hpodder has a configuration file in which you can set various  options.
       This file normally lives under ~/.hpodder/hpodder.conf.

       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.

       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

       Let's  start by looking at an example file, and then proceed to examine
       all the options that are available.


       ; 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


       ; The following line tells hpodder that
       ; you have already gone through the intro.
       showintro = no

       maxthreads = 2
       progressinterval = 1

       ; Store this particular podcast somewhere else
       downloaddir = /nfs/remote/podcasts

       ; And we don't care as much about disabling it
       podcastfaildays = 5

       In this example, you saw some "general"  options,  such  as  showintro.
       There are two other sections represented: 31 and DEFAULT.

       Whenever  hpodder  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 DEFAULT section.  If it still doesn't
       find an answer, it consults its built-in defaults.

       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 downloaddir overrides the default.

       These are specified in the general section.

              The maximum number of simultaneous download threads that will be
              active  at  any given time.  hpodder can download multiple files
              at once,  and  this  options  says  how  many  it  can  download
              simultaneously.  It defaults to 2.

              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 hpodder over a very low-
              bandwidth link and are concerned about flooding it  with  status

              The  first  time  you  run fetch, hpodder automatically writes a
              configuration file for you that sets this option  to  no.   This
              prevents  you  from  having  to  do the new user intro more than

       These options may be specified in DEFAULT or in a per-podcast  section.
       If   placed  in  DEFAULT,  they  will  apply  to  all  podcasts  unless

              The main directory into which all podcasts should be stored.  It
              will be created by hpodder when necessary if it does not already
              exist.  The default is ~/podcasts

              The minimum number of attempts to download this  episode  before
              the  episode  will be considered to be marked Error.  Default is

              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.

              How  to  name downloaded files.  This pattern is relative to the
              downloaddir.  The default is %(safecasttitle)s/%(safefilename)s

              This option will be provided with  several  replaceable  tokens.
              Tokens  have  the  form %(tokname)s.  That is, the percent sign,
              the token name in perenthesis, and then an "s"  character.   The
              tokens made available for this option are:

              castid The numeric ID for this podcast

              epid   The numeric ID for this episode

                     The  title  of  the  podcast,  as  specified in the feed.
                     Special characters, such as spaces or exclamation  marks,
                     are converted to underscores.

                     The  title of this episode, as specified in the podcast's
                     feed, with special characters converted to underscores.

                     The component from the URL for  this  episode  after  the
                     last  slash in the URL, with special characters converted
                     to underscores.

              The minimum number of attempts to download this  podcast  before
              the  episode  will be considered to be marked disabled.  Default
              is 15.

              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.

       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.  Extreme caution must be exercized to properly quote  these
       variables  when using them in shell commands or scripts.  The following
       environment variables are set:

       CASTID The numeric ID for this podcast

              The title of the podcast, verbatim

              The on-disk filename where this episode has been stored

       EPID   The numeric epidose ID for this episode

              The title of this episode, as specified in the podcast's feed.

       EPURL  The URL of this episode.

              The URL of the podcast's feed.

              The title of the podcast, as specified  in  the  feed.   Special
              characters,  such  as spaces or exclamation marks, are converted
              to underscores.

              The title of this episode, as specified in the  podcast's  feed,
              with special characters converted to underscores.

       Here are the supported commands:

              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.

              This  command  provides a user-configurable post-processing hook
              for downloaded podcasts.  It is only invoked on files whose type
              matches  the  postproctypes list.  This command is the very last
              step in the downloading process.

              The default value adds ID3 tags to MP3 files.  It is:  id3v2  -A
              "${CASTTITLE}"   -t   "${EPTITLE}"   --WOAF   "${EPURL}"  --WOAS
              "${FEEDURL}" "${EPFILENAME}"

       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 gettypecommand, 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.

              This  is  the  comma-separated  list  of  MIME  types  on  which
              postproccommand  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

              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.   hpodder  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-


       Internally,  hpodder  uses  the  Curl  application to perform downloads
       across the Internet.  Curl is a remarkably  flexible  application,  and
       hpodder  takes  advantage  of  that  to  provide  you  with quite a few

       You can customize  Curl  as  much  as  you  like  by  creating  a  Curl
       configuration  file  in ~/.hpodder/curlrc.  Please see curl(1) for more
       details on the content of that file.

       Some things you can do with this file include restricting  the  maximum
       download rate, suppressing or adjusting the progress meter, configuring
       proxies, etc.


       Here are a few tips and hints to make hpodder more pleasant for you.

       If your connections must go through a proxy, you have two options:  set
       an   environment   varilable   or   configure   the   proxy   in   your
       ~/.hpodder/curlrc.  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.

       Sometimes, you may not want  hpodder  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 ~/.hpodder/curlrc  file.   Put  in  it
       something like this:


       This will limit the download rate to 20 KB/sec.

       This  rate  limitation  is imperfect and may not do well during update,
       but it should do exactly what you want during download.


       hpodder 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 curl(1) for more
       details.   As  specified  in  the  Per-Podcast Command Options section,
       hpodder  will  also  set  certain  variables  for  post-processing   of
       downloaded files.


       · The  Extensible  Markup  Language  (XML) <URL:>
         standard (W3C)

       · RSS 2.0 <URL:> (Harvard Law)

       · HTTP 1.1, FTP, plus SSL/TLS and any other protocols supported by Curl

       · ID3 v1 and v2


       hpodder,  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:

       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.

       This  program  is  distributed  in the hope that it will be useful, but
       WITHOUT  ANY  WARRANTY;  without   even   the   implied   warranty   of
       General Public License for more details.

       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

       The GNU General Public License is available in the file COPYING in  the
       source   distribution.    Debian  GNU/Linux  users  may  find  this  in

       If the GPL is unacceptable for your uses, please e-mail me; alternative
       terms can be negotiated for your project.


       hpodder,  its  modules,  documentation,  executables,  and all included
       files,   except   where   noted,   was   written   by   John    Goerzen
       <>   and  copyright  is  held  as  stated  in  the
       COPYRIGHT section.


       curl(1), id3v2(1)

       The hpodder homepage at  <URL:>, a general
       description of podcasting at