===========================================
Podcast Downloader - README
===========================================

NAME
    podcast-downloader - A script to download podcasts from an RSS feed and optionally tag their metadata.

VERSION
    1.0.1

CHANGELOG
	The changelog can be found at https://source.willem.com/podcast-downloader/CHANGELOG.txt.

DESCRIPTION
    This bash script simplifies downloading podcast episodes from an RSS feed. It provides options to save episodes to a directory of your choice and to tag them with a custom album name (if desired). The script is highly customizable and suitable for tech-savvy users.

    Key Features:
    - Downloads media files from a specified RSS feed.
    - Supports dynamic file extensions (e.g., mp3, m4a).
    - Normalizes filenames for safety and clarity.
    - Optionally tags podcasts with an album name using `id3v2`.

USAGE
    ./podcast-downloader.sh -u <RSS_FEED_URL> [-d <DOWNLOAD_DIR>] [-a <ALBUM_NAME>]

    Options:
        -u  Specify the RSS feed URL (required).
        -d  Specify the directory for downloads (default: ~/Podcasts).
        -a  Specify the album name for tagging (optional). If omitted, no metadata will be tagged.
        -h  Show this help message and exit.

    Examples:
        # Download podcasts to the default directory without tagging
        ./podcast-downloader.sh -u "https://example.com/feed.xml"

        # Download podcasts to a custom directory with album tagging
        ./podcast-downloader.sh -u "https://example.com/feed.xml" -d ~/MyPodcasts -a "My Favorite Podcast"

REQUIREMENTS
    The following tools must be installed on your system:
    - bash (tested on version 5.x or higher)
    - wget (for downloading files)
    - awk (used for parsing RSS feeds)
    - id3v2 (optional, for tagging MP3 files)

INSTALLATION
    1. Copy the script to a directory in your system's PATH (e.g., /usr/local/bin):

        cp podcast-downloader.sh /usr/local/bin/podcast-downloader
        chmod +x /usr/local/bin/podcast-downloader

    2. Verify the script is executable:

        podcast-downloader -h

NOTES
    - Parsing of RSS feeds relies on standard XML formatting. It assumes the presence of <enclosure>, <title>, and <pubDate> tags.
    - The script normalizes filenames to avoid invalid characters or duplicates.
    - Temporary files are stored in a secure location and cleaned up automatically after execution.
    - Media files are downloaded only if they do not already exist in the target directory.

TROUBLESHOOTING
    - "Error: RSS feed URL is required."
        Ensure the -u option is provided with a valid RSS feed URL.

    - "Error: Failed to download RSS feed. Check the URL."
        Verify the URL is correct and accessible.

    - "id3v2 not installed; skipping album tagging."
        Install id3v2 if you want to use the album tagging feature:

            sudo apt install id3v2

AUTHORS
    Willem L. Middelkoop (willem.com)

LICENSE
    This script is licensed under the GNU General Public License v3.0.
    See <https://www.gnu.org/licenses/> for more details.

COPYRIGHT
    Copyright (C) 2025 Willem L. Middelkoop

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program. If not, see <https://www.gnu.org/licenses/>.

FEEDBACK AND CONTRIBUTIONS
	For more information or to report issues, please visit https://source.willem.com/podcast-downloader/ 
	or contact Willem L. Middelkoop through https://willem.com.