DOCSEARCHbyAlgolia
Submit Docs

podcast-dl

repository·main·Indexed 20 days ago

https://github.com/lightpohl/podcast-dl

A command-line interface (CLI) for downloading and archiving podcasts via their RSS feeds. Version 11.7.5. It supports concurrent downloads, episode filtering by date or regex, metadata extraction, and audio processing via ffmpeg (including format conversion and bitrate adjustment). Features include a JSON-based archive system to prevent duplicate downloads and a flexible templating system for filenames and directories.

Tokens
12.2K
Snippets
49
Records
57
Agent score
67%

What's inside podcast-dl

  1. Configure filename and directory templates

    main

    podcast-dl supports dynamic templates for filenames and directories using double braces {{keyword}}. These keywords are replaced with metadata from the podcast feed or specific episodes.

    Template Keywords for --out-dir and --archive

    • podcast_title: Title of the podcast feed.
    • podcast_link: The link value from the podcast feed (usually the homepage URL).

    Template Keywords for --episode-template

    • title: Episode title.
    • release_date: Date in YYYYMMDD format.
    • release_year: Year (YYYY).
    • release_month: Month (MM).
    • release_day: Day (DD).
    • episode_num: Position in the feed.
    • url: URL of the audio file.
    • duration: Duration in mm:ss format.
    • podcast_title: Title of the podcast feed.
    • podcast_link: Link to the podcast feed.
    • guid: The episode's GUID.

    Custom Matchers via --episode-custom-template-options

    You can use regex matchers to extract values from the episode title. These are accessed in templates using custom_<n>, where <n> is the zero-based index of the matcher. If no match is found, it results in an empty string.

    Template Keywords for --exec

    When using the --exec command, the following variables are available:

    • episode_path: Full path to the downloaded episode.
    • episode_path_base: Directory containing the episode.
    • episode_filename: Filename including extension.
    • episode_filename_base: Filename without extension.
    • url: URL of the audio file.
    # Example: Organize by podcast title and use a date-title format for episodes
podcast-dl --out-dir "./{{podcast_title}}" --episode-template "{{release_date}}-{{title}}" [RSS_URL]

  2. Install podcast-dl via Binaries

    main

    You can download pre-compiled binaries for your specific operating system from the official releases page. Once downloaded, you can run the tool directly from your terminal.

    podcast-dl --url <PODCAST_RSS_URL>

  3. Use an HTTP Proxy with podcast-dl

    main

    To route traffic through an HTTP proxy, set the GLOBAL_AGENT_HTTP_PROXY environment variable to your proxy URL and include the --proxy flag in your podcast-dl command. This is useful for corporate networks or accessing region-restricted content.

    export GLOBAL_AGENT_HTTP_PROXY="http://127.0.0.1:12345"
podcast-dl --proxy --url "https://example.com/podcast.rss"

  4. Use an HTTPS Proxy with podcast-dl

    main

    To route HTTPS traffic through a proxy, set the GLOBAL_AGENT_HTTPS_PROXY environment variable.

    Important: The proxy URL must use the http:// protocol, even when configuring the HTTPS proxy, because the proxy server itself handles the HTTPS connection.

    export GLOBAL_AGENT_HTTPS_PROXY="http://127.0.0.1:12345"
podcast-dl --proxy --url "https://example.com/podcast.rss"

  5. Use a proxy with authentication

    main

    If your proxy server requires credentials, include the username and password in the GLOBAL_AGENT_HTTP_PROXY environment variable using the format http://username:password@host:port.

    export GLOBAL_AGENT_HTTP_PROXY="http://username:password@127.0.0.1:12345"
podcast-dl --proxy --url "https://example.com/podcast.rss"

  6. Configure both HTTP and HTTPS proxies

    main

    To ensure all traffic (both standard HTTP and encrypted HTTPS) is routed through the proxy, set both GLOBAL_AGENT_HTTP_PROXY and GLOBAL_AGENT_HTTPS_PROXY environment variables.

    export GLOBAL_AGENT_HTTP_PROXY="http://127.0.0.1:12345"
export GLOBAL_AGENT_HTTPS_PROXY="http://127.0.0.1:12345"
podcast-dl --proxy --url "https://example.com/podcast.rss"

  7. Run podcast-dl using npx

    main

    If you have Node.js installed, you can run podcast-dl without a permanent installation using npx. You must provide the --url flag followed by the RSS feed URL of the podcast you wish to download.

    npx podcast-dl --url <PODCAST_RSS_URL>

  8. Configure logging via `LOG_LEVEL`

    main

    Control the verbosity of the console output using the LOG_LEVEL environment variable:

    • static: All logs and errors are outputted, but animations are disabled.
    • quiet: Only important info and non-critical errors (e.g., download start) are logged.
    • silent: Only critical error messages are logged.

  9. How feed and episode metadata is handled with archives and overrides

    main

    The tool manages metadata for both feeds and individual episodes (items) using two primary mechanisms to prevent redundant writes:

    1. Archives: If an archive is provided, the tool checks if the key (for feeds) or archiveKeys (for episodes) already exists in the archive. If found, the metadata write is skipped.
    2. Local Files: By default, if a metadata file already exists at the specified outputPath, the tool skips the write to avoid overwriting existing data.
    3. Overrides: If the override flag is set to true, the tool will bypass both the archive check and the local file existence check, forcing a write to the outputPath and updating the archive.

    This logic ensures that metadata is only captured once unless explicitly requested otherwise.

  10. How podcast-dl handles episode selection and filtering

    main

    When running podcast-dl, you can precisely control which episodes are targeted for download using several filtering mechanisms. These filters are applied to the feed items before the download process begins.

    Key Filtering Concepts:

    • Pagination: Use --limit and --offset to grab specific chunks of the feed.
    • Chronological Filtering: Use --after and --before to target specific time ranges.
    • Regex Matching: Use --episode-regex to include episodes matching a pattern, or --episode-regex-exclude to skip them.
    • Structural Filtering: Use --season to target specific podcast seasons.
    • Ordering: Use --reverse to flip the order of processing (useful for getting the newest episodes first if the feed is ordered oldest-to-newest).

    These filters work together to create a targetItems list, which is then passed to the asynchronous download engine.

  11. Configure download concurrency and threads

    main

    When using downloadItemsAsync, you can control how many downloads happen simultaneously using the threads option. This is useful for balancing download speed against system resources or avoiding rate limits.

    • Set threads: 1 for sequential downloads.
    • Set threads: N (where N > 1) to download N items in parallel using p-limit internally.

  12. Adjust filename length limits via `MAX_LENGTH_FILENAME`

    main
    By default, the maximum length for a generated filename is 255 characters. If you encounter issues with non-standard feeds or specific OS limitations, you can adjust this limit using the MAX_LENGTH_FILENAME environment variable.