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.
- 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
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
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
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!
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"
.
-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
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 |
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 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.
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:
- Fork the repository
- Create a new branch for your feature or bug fix
- Make your changes and commit them with descriptive commit messages
- Push your changes to your forked repository
- Submit a pull request to the main repository
TaleCast is released under the MIT License.