Poca

Poca is a fast, multithreaded and highly customizable command line podcast client, written in Python 3.

Features

  • Maximum amount. Specify how many episodes the subscription should get before deleting old episodes to make room for new ones.
  • Override ID3/Vorbis metadata. If you want Savage Love to have Dan Savage in the artist field (rather than The Stranger), poca will automatically update the metadata upon download of each new episode. Or set genre to be overwritten by Podcast as a default.
  • Filter a feed. Only want news reports in the morning or on Wednesdays? Use criteria such as filename and title, or the hour, weekday or date of publishing to filter what you want from a feed.
  • Rename files automatically. Not all feeds have sensibly named media files. Specify a renaming template like date_title to know what you’re dealing with or to get alphabetical ordering to match chronology.
  • From the top. A latecomer to Serial or other audiobook style podcasts? Specify from_the_top to get oldest episodes first, rather than the latest. To move on to later episodes simply delete old ones and poca will fill up with the next in line.
  • Keeping track. Poca logs downloads and removals to a local file so you easily see what’s changed. Or configure it with an SMTP server and get notified when a feed stops working.
  • Manage your shows by editing an easy-to-understand xml file. Or use the accompanying tool to add, delete, sort them, or get info about their publishing frequency, average episode length and more.

Poca also: has excellent unicode support for feeds, filenames and tags, gets cover images for feeds, has the ability to spoof user agents, can pause your subscriptions, deals intelligently with interruptions, updates moved feeds (HTTP 301) automatically, and more.

Interface

asciicast

All configuration is done in a single XML-format file. For cron job compatibility, Poca has a quiet mode in addition to normal and verbose.

Installation

You can install poca from pypi using pip. Be mindful that poca is python 3 so use pip3:

pip3 install poca

If you are upgrading from any pre-1.0 release, please see this Upgrade to 1.0 notice. To remove Poca simply do:

pip3 uninstall poca

Requirements

  • Python 3.6 or later
  • Third-party modules: requests feedparser lxml mutagen
  • Pip will automatically install any one of these found missing
  • A unicode capable terminal is recommended but not required
  • Due to dependencies of third-party modules (lxml requires libxml2 v. 2.9.2 and libxslt 1.1.27) distros no older than Ubuntu 18.04 are recommended.
  • For use on WSL, the “-g wsl” flag is recommended as it will substitute out characters known not to work on WSL (see https://github.com/microsoft/WSL/issues/75)

Quickstart

[ ~ ] poca
No config file found. Making one at /home/user/.poca/poca.xml.
Please enter the full path for placing media files.
Press Enter to use default (/home/user/poca): /tmp/poca
 ⚠ Default config succesfully written to /home/user/.poca/poca.xml.
Please edit or run 'poca-subscribe' to add subscriptions.

[ ~ ] poca-subscribe add
Url of subscription: http://crateandcrowbar.com/feed/

Author: The Crate and Crowbar                            PUBLISHED / 5 WEEKS
Title:  The Crate and Crowbar

Last episode: Episode 216: Videocrates Crowdog                       ▮
Published:    24 Nov 2017                                            ▮
                                                                     ▮     ▮
Avg. size of episode:   52 Mb                            ▮  ▮     ▮  ▮  ▮  ▮
Avg. length of episode: 1h 52m                           M  T  W  T  F  S  S

Title of subscription: (Enter to use feed title)
Maximum number of files in subscription: (integer/Enter to skip) 5
Get earliest entries first: (yes/no/Enter to skip) no
Category for subscription (Enter to skip): gaming
To add metadata, rename or filters settings, please edit poca.xml

[ ~ ] poca --verbose
THE CRATE AND CROWBAR. 5 ➕
 ⇵ CCEp214.mp3  [56 Mb]
 ⇵ LGCEp004.mp3  [35 Mb]
 ⇵ CCEp215.mp3  [61 Mb]
 ...

Configuration

The poca.xml file contains all poca’s general and subscription specific configuration. To get started simply run poca once to get a basic config file placed in ~/.poca.

The configuration file is divided into three main parts:

<poca version="1.0">
  <settings>
  ...
  </settings>
  <defaults>
  ...
  </defaults>
  <subscriptions>
  ...
  </subscriptions>
</poca>
  • Settings: Contains general settings
  • Subscriptions: Contains a list of all the podcasts you want to subscribe to
  • Defaults: Options in defaults are similar to those in subscriptions, only they apply globally (unless overridden).

Running

Poca is run by issuing the poca command. Subscriptions can be managed by using the helper script poca-subscribe.

Changelog

Version 1.1

Features

  • Filenames: Auto-detect and fix filename collisions (e.g. if all files are named media.mp3)
  • Metadata: Tagging now extends to mp4 files (as well as mp3 and files using vorbis comments for metadata)
  • Metadata: Can now use ‘comment’ field to overwrite comments on ID3 tags (all existing comment frames are deleted)
  • Metadata: Empty values in metadata elements (e.g. <album></album> or <album/>) can now be used remove the frame entirely.
  • Metadata: <chapters></chapters> is a special case of that. Adding the chapters element can be used to remove the table of contents and chapters frames (CTOC and CHAP). It will disregard any text value inserted.

Fixes

  • Filenames: Filesystem safe names. poca will automatically adapt the default or chosen filename to create legal filenames on the filesystem used for the podcast files (e.g. remove question marks from filenames on NTFS). It will not by default ‘degrade’ the filename more than needed for any given file system (see below).
  • Filenames: New setting to manually set filename permissiveness: Override the default behaviour by ordering poca to start at a lower level of filename character permissiveness.
  • Config: File permissions check is more granular. Checks out as long as user has read permission to poca.xml and write permission to db and media folder. Note: A read-only config file prevents poca from updating the url if status == 301.
  • Filters: Filename filtering has been fixed
  • Filters: Filtering errors are now reported
  • Download: Cover images are downloaded once, and only downloaded again if there is a new one, rather than with each update.
  • Improved unicode support (better testing for support and fallbacks)

Version 1.0

  • Added file renaming options (#16)
  • More consistent output in normal and verbose mode
  • audiosearch api removed again due to service closure (#87)
  • Bugfixes, quibbles and niggles aplenty

Version 0.9

  • Artificial track numbers (#43)
  • Support for tagging with other formats than mp3: Ogg, opus, mp4, flac, … (#18)
  • Reintroduced support for id3v2.3
  • poca-subscribe search: Seach for shows with audiosearch’s api
  • ‘Preview’ feed in poca-subscribe’s add command (#55)
  • Multithreading support with option for concurrent downloads as well as concurrent updates (#45)
  • Subscription URLs are automatically updated when feeds move (HTTP status code 301)
  • New dependency: requests for downloads due to downloading in threads

Version 0.8

  • New dependency: lxml for greatly simplified configuration parsing
  • System defaults in case of missing or bad config and user set global subscription defaults
  • New script: poca-subscribe, a cli tool to manage subscriptions

Version 0.7

  • Log: Terse logging (skip writing about subscription if nothing has changed) (#32)
  • Email logging: A sensible email logging system (#26)
  • Style: Investigating Syntastic complaints (#39)
  • Bug fix: Hangs on feeds without entry size info (#40)
  • Bug fix: Crash on entries without enclosures (#41)

Version 0.6

  • max_number: Limit by number of files (#14)
  • max_mb has been dropped in favour of max_number
  • filters: Filter entries by filename, date, … (#29)
  • from_the_top: Option to start podcast from the beginning (#28)
  • Download cover image from feed (#25)
  • Testing for unicode exceptions in feed treatment and mp3 metadata (#17)
  • Spoofed useragent introduced as fallback if urllib is denied

Version 0.5

  • Completed port to Python 3
  • Completely revised and simplified stream and log output
  • Mp3 tagging reimplemented
  • New download function with proper timeouts

Version 0.4

  • Reduced functionality port to Python3