Skip to content

Latest commit

 

History

History
156 lines (110 loc) · 9.14 KB

README.md

File metadata and controls

156 lines (110 loc) · 9.14 KB
Raw

TaleCast

TaleCast is a simple and powerful CLI podcast manager that makes it easy to search, add, and manage your favorite podcasts directly from the terminal.

Demo

Features

  • Search and add podcasts directly from the terminal
  • Configurable episode downloading options
  • MP3 tag normalization
  • Granular configuration control for each podcast
  • Backlog mode to catch up on old episodes at your own pace
  • Download hook for post-download processing
  • OPML export and import
  • Git-friendly download-tracker (textfile where 1 episode == 1 line)
  • Advanced pattern-matching for naming files and more
  • Custom ID3v2 tag support
  • Parallel downloads
  • Partial download support
  • Ability to print downloaded paths to stdout for easy piping
  • Pretty graphics
  • Filter episodes to sync or export using regex patterns
  • Built-in symlink support

Installation

Using Cargo

To install TaleCast using Cargo, you'll need to have Rust installed. If you haven't used Rust before, run the shell command from the official website: https://www.rust-lang.org/learn/get-started

Once Rust is installed, you can install TaleCast with the following command:

cargo install talecast

Arch Linux (AUR)

TaleCast is available in the Arch User Repository (AUR) for Arch Linux users. You can install it using your preferred AUR helper, such as paru or yay.

To install TaleCast with paru, run the following command:

paru -S talecast-git

Other Package Managers

If you have experience packaging for a package manager not listed here, it would be greatly appreciated if you add it and let me know about it!

Usage

Adding Podcasts

There are several ways to add podcasts to TaleCast:

  • Search for podcasts with talecast --search $NAME
  • Add a podcast directly with talecast --add $PODCAST_URL $PODCAST_NAME
  • Edit the podcasts.toml file directly (see the 'Configuration' section below)

For finding podcast URLs, I recommend using https://podcastindex.org/. On the page of a given podcast, click 'copy rss' to get the URL you should use.

If you add podcasts from the command line, you can combine it with the catch-up argument to only download upcoming episodes. For example: talecast -cs "this american life".

Command Line Options

  -i, --import <FILE>      Import podcasts from an OPML file
  -e, --export <FILE>      Export your podcasts to an OPML file
  -p, --print              Print the downloaded paths to stdout
  -c, --catch-up           Configure to skip episodes published prior to current time. Can be combined with filter, add, and import
  -a, --add <URL> <NAME>   Add new podcast
  -f, --filter <FILTER>    Filter which podcasts to sync or export with a regex pattern
      --config <FILE>      Override the path to the config file
      --edit-config        Edit the config.toml file
      --edit-podcasts      Edit the podcasts.toml file
  -s, --search <QUERY>...  Search for podcasts to add
  -h, --help               Print help
  -V, --version            Print version

Configuration

To edit the global config, run talecast --edit-config. To edit the podcasts, run talecast --edit-podcasts.

These files are located in ~/.config/talecast/config.toml and ~/.config/talecast/podcasts.toml respectively, unless your XDG_CONFIG_HOME environment variable is set to something else.

The way configuration works is that you can set a 'global value' that applies to all podcasts in the config.toml file. However, you can override these settings by specifying the same setting under a given podcast in the podcasts.toml file. If a value is not required, you can have it configured globally but disable it on specific podcasts with $SETTING = false.

Setting Description Required Per-Podcast Global Default
url The URL to the XML file of the podcast Yes ✅ ❌ No default, must be specified
download_path The path where episodes will be downloaded Yes ✅ ✅ "{home}/talecast/{podname}"
name_pattern Pattern determining the name of episode files Yes ✅ ✅ "{pubdate::%Y-%m-%d} {rss::episode::title}"
id_pattern Episode ID for determining if an episode has been downloaded Yes ✅ ✅ "{guid}"
download_hook Path to script that will run after an episode is downloaded No ✅ ✅ None
partial_path The path where partially downloaded episodes are stored No ✅ ✅ download_path
tracker_path Path to textfile that tracks downloaded episodes No ✅ ✅ download_path/.downloaded
max_days Episodes older than this won't be downloaded No ✅ ✅ None
max_episodes Only this number of past episodes will be downloaded No ✅ ✅ None
earliest_date Episodes published before this date won't be downloaded No ✅ ✅ None
id3_tags Custom tags that MP3 files will be annotated with No ✅ ✅ []
symlink Directory where downloaded files will be symlinked to No ✅ ✅ None
backlog_start Start date of when backlog mode calculates from No ✅ ❌ None
backlog_interval How many days pass between each new episode in backlog mode No ✅ ❌ None

Pattern System

TaleCast provides a way to generate dynamic text using a pattern system. There are two types of patterns: unit patterns that take no input, and data patterns where you provide an input.

Unit Patterns:

Pattern Evaluates to
guid The GUID of an episode
url The URL to the episode's enclosure
podname Configured name of the podcast
home The path to your home directory

A good example of these is the default value of the download_path setting.

Data Patterns:

Pattern Description
rss::episode Represents the XML of an individual episode. The data it takes in is the name of an XML tag. The output is the contents of that tag.
rss::channel Represents the XML of a podcast. The data it takes in is the name of an XML tag. The output is the contents of that tag.
pubdate The time the episode was published. Takes in a formatter string.

Look at the default value of the name_pattern setting for an example of how to use them.

Note that not all patterns are available for each setting. For example, the download_path can't use information specific to an episode.

Backlog Mode

Backlog mode is a way to systematically go through the backlog of a podcast, starting from the first episode. It's perfect for podcasts where older episodes are as relevant as newer ones, and especially if you're supposed to go through them chronologically.

To use backlog mode, set the backlog_start date and then sync. TaleCast will download the first episode of the podcast. After backlog_interval days have passed, it will download the second episode, and so on.

Contributing

If you encounter any bugs or have feature requests, please use the GitHub issue page. If you're reporting a bug, make sure you have the latest version of TaleCast in case it has already been fixed.

Contributions are welcome! If you'd like to contribute to TaleCast, please follow these steps:

  1. Fork the repository
  2. Create a new branch for your feature or bug fix
  3. Make your changes and commit them with descriptive commit messages
  4. Push your changes to your forked repository
  5. Submit a pull request to the main repository

License

TaleCast is released under the MIT License.