Subscriptions¶
Subscriptions are podcast feeds you want poca to follow and (usually)
download any new entries from. You create a subscription in poca by adding an
xml subscription
element with all the relevant settings to your
poca.xml
configuration file. Using the add command from
poca-subscribe is a nice shortcut if you don’t like editing xml.
Contents
Structure¶
Each <subscription>
is created as an element under the
<subscriptions>
element. The structure of a subscription element is as follows:
<subscription category="..." state="...">
<title>...</title>
<url>...</url>
<max_number>...</max_number>
<from_the_top>...</from_the_top>
<track_numbering>...</track_numbering>
<metadata>
<headerfield1>...</headerfield1>
<headerfield2>...</headerfield2>
<headerfield3>...</headerfield3>
</metadata>
<rename divider="..." space="...">
<title/>
<episode_title/>
<date/>
<uid/>
<org_name/>
</rename>
<filters>
<filename>...</filename>
<title>...</title>
<weekday>...</weekday>
<hour>...</hour>
<after_date>...</after_date>
</filters>
</subscription>
Required elements¶
subscription
entries without the required elements are silently skipped
during updates.
title¶
Title of show/subscription. Used only to name the subscription subdirectory under the base_dir, not to insert into ID3 headers.
Before attempting to download files for a subscription, poca checks to see if the subscription subdirectory exists and the user has permission to write to it. If not, poca attemps creation of the subdirectory. Failure at this stage causes poca to skip the subscription. The title must be a legal directory name on the filesystem used (linux filesystems have almost no restrictions, NTFS and FAT have a few).
Optional elements¶
Note that all optional elements in a subscription can also be added to the
<defaults>
section to be applied globally.
max_number¶
The maximum number of episodes (integer) for the subscription to have at any
one time. Only the max_number
most recent episodes will be downloaded. If
this is not set poca will - unless otherwise restricted - download all files
in the feed. This setting replaces the max_mb
setting in versions of poca
prior to 0.6.
from_the_top¶
This is an alternative to default mode. The latter prioritises later episodes
over newer: If max_number
is 4, poca will download the latest 4 episodes.
If from_the_top is set to ‘yes’, poca will instead start at the beginning,
downloading the oldest 4 episodes. To move forward in the feed, you simply
delete old files (episodes 1 and 2). Poca will detect this and fill up the
max_number
quota with newer files (episodes 5 and 6). This is useful for
audiobook-style podcasts like Serial or working your way through old
episodes of a newly discovered podcast.
track_numbering¶
Track numbers in podcasts are hit or miss. Some include them, some don’t.
Most players will then simply play the files in the order of filenames. If
you want to ensure that the episodes have track numbers set to yes
which
will overwrite the episodes track number with an artificial track number that
starts at 1 with the first episode poca downloads (so if you start
subscribing at episode 247, this will get tracknumber 1 etc.) Set to
if missing
to only insert track numbers when they are absent.
This can be a useful setting in <defaults>
. Set to no
or leave the
option out of your subscription to leave the track number as is.
Note that track numbers can also be overwritten using the tracknumber
element in metadata (see below). That, however only sets track numbers to a
static value - or if no value is entered removes the track numbers entirely.
metadata¶
With 1.1 tagging now works for m4a files as well as vorbis comments (ogg, opus, flac amongst others) and id3 tags.
Each element under metadata is a field in the id3/m4a/vorbis comment header that should be overwritten or added (if there is no such field in the original metadata). If you do not wish to touch the vorbis comment/id3 headers simply leave out the metadata element altogether.
- Example: The ‘Savage Love’ podcast has the publisher ‘The Stranger’ as the
value of the ‘artist’ field. Creating an
<artist>Dan Savage</artist>
element tags the downloaded files with Dan Savage instead. - Example: If your player arranges files by genre, it might be advantageous
to have all podcasts genre labelled ‘podcasts’ in a uniform fashion by
inserting a
<genre>podcast</genre>
element either in each individual subscription or in thedefaults
.
A list of all the field names that poca recognises for id3 and m4a headers can
be printed by running poca-subscribe tags
using either the --mp3
or
the --mp4
flag.
Relying on mutagen’s “easy” modules, poca allows you to use title
for
track title, artist
for artist, etc. Vorbis comment tags are not restricted
in what keys can be used (though all vorbis comment keys must be ascii) but this
Xiph.org list can be used as a
reference for tag names convention.
Any empty value, i.e.:
<album></album>
or:
<album/>
will cause the frame to be removed rather than overwritten. This especially
true for the <chapters/>
element, as that can only be used to remove. poca will
disregard any text value associated with it and will only use it to remove CTOC
and CHAP frames from id3 tags in the subscription.
rename¶
An option to rename the media files downloaded. Not all feeds name their media consistently, helpfully (e.g. all files are named media.mp3) or alphabetically (e.g. just using the episode title rather than conventions like padded-tracknumber_title).
Renaming is done by slotting in the new name components as XML elements in the file name order desired. The available components from the feed and the user settings are as follows.
title
: The title of the subscription as indicated by the userepisode_title
: The title of the episode as indicated by the publisher in the feeddate
: The date at which the episode was published to the feed (aka pubdate). The date is rendered in the format YYYY-MM-DD.uid
: The episode’s unique identifier in the feed. This can be a number (7932
), a random string (d39gs9db3f6ihhbzx5
) or the url for the episode. All non-alphanumerical characters are discarded for naming purposes.org_name
: The original filename for the episode. In case you just want to preface it with a date or uid.
Each component can be used as many times as desired or not at all. The components can come in any order desired.
Please note, that the rename pattern is resolved before the file is downloaded. Therefore there is no option to make use of media metadata (id3/vorbis comments) when renaming. Any non-available components (e.g. a feed does not have uids for entries) will be replaced with ‘missing’ or similar.
By default the components are divided by underscores when assembling the full
file name. Alternatively you can set the divider
attribute and give it
the desired divider value. Spaces in the filename originating from using a
title or similar can be replaced by using the space
attribute. Spaces
will be replaced with the value of the attribute. Note that the resulting
filenames are sanitized, see the filenames section in Settings.
Example:
<rename divider="_" space="_">
<date/>
<org_name/>
</rename>
The above configuration as applied to the Python Bytes feed result in files named like this:
2017-10-25_your-technical-skills-are-obsolete-now-what.mp3
2017-11-02_bundling-shipping-and-protecting-python-applications.mp3
filters¶
The filters element should contains one or more of the following tags that filter the entries in the feed based on various criteria. All filters are positive in the sense that the entry must meet the criterion to be included. Each filter can only be used once per subscription.
filename¶
The filename of the entry must match this string in order to be included.
Note that the value is interpreted as a regex, so certain characters should
be escaped (e.g. a literal point should be written ‘.’) Apart from this it
is perfectly possible to use simple strings and ignore the regex aspect. The
filename matched is the original filename, not those resulting from using
rename
(see above). Example:
<filename>^episode</filename>
will only include regular Judge John Hodgman
episodes and not the special cheese shows, shootin’ the bries that have
filenames starting with “shootin’”.
title¶
The same as above, only for the title in the RSS feed (not in the music file’s metadata). Example:
<title>Wires</title>
only gets the ‘Within the Wires’ episodes from the
Welcome to Nightvale feed.
hour¶
The hour (24h-format) at which the entry was published. This is useful for podcasts that put out more episodes a day than you need, e.g. news broadcasts. Example:
<hour>21</hour>
only gives you the evening edition of BBC’s Newshour.
weekdays¶
Excludes all episodes not published on the specified weekdays. Each weekday to be included is written as a single digit where Monday is 0, Tuesday is 1, etc, up to 6 for Sunday. Example
<weekdays>024</weekdays>
to get Monday, Wednesday, and Friday episodes.
after_date¶
Only includes episodes published on or at a later time than the specified
date. Format is YYYY-MM-DD. This is useful is you don’t want to restrict the
max_number
of the subscription but still avoid downloading the entire
back catalogue. Example:
<after_date>2016-08-23</after_date>
will ignore all episodes published
before August 23rd 2016.
Optional attributes¶
Each subscription tag can have two optional attributes:
category¶
Setting a category will sort the outputted list of poca-subscribe’s list
command into groups, each category being grouped together. Example:
<subscription category="news">...</subscription>
state¶
The state attribute has two valid settings: active
and inactive
. If a
subscription does not have the attribute it is counted as being active.
Active subscriptions are updated as normal. Inactive subscriptions are passed
over when poca is run. Additionally, setting a subscription’s state to
inactive using poca-subscribe’s toggle
command will delete old audio
files. Example:
<subscription state="inactive">...</subscription>
Example¶
Here is an example of a subscription to a news in French podcast:
<subscription category="news">
<title>francais facile</title>
<url>http://www.rfi.fr/radiofr/podcast/journalFrancaisFacile.xml</url>
<max_number>3</max_number>
<metadata>
<artist>Radio France Internationale</artist>
<album>Journal en français facile</album>
<genre>podcast</genre>
</metadata>
<rename>
<title/>
<date/>
</rename>
</subscription>