YTRSS - automatic podcast maker#

Program to automatic download any types of files from Internet and generates podcast from them.

https://img.shields.io/readthedocs/ytrss.svg

https://img.shields.io/github/last-commit/rafyco/ytrss.svg

https://img.shields.io/github/issues/rafyco/ytrss.svg

https://img.shields.io/docker/v/rafyco/ytrss

https://img.shields.io/github/license/rafyco/ytrss.svg

Description#

YTRSS is a program that checks defined sources and downloads a movie or sound files from them and arrange them to podcast files. It can be highly configured with many plugins that add any other destinations.

The program in basic version use youtube_dl script to download files, so it cooperates with all services implements by this library. However user can extends this capabilities by his own custom plugins with external Downloaders.

Requires#

To download files, ytrss use following programs:

yt-dlp

Installation#

The installation can be carried out in two ways. You can download packages from PyPi repository or install it from sources.

For installation from PyPi you can use pip program. It is likely that you must use pip3 instead pip.

pip install ytrss

You can also use source from github repository to install ytrss. To make that download code and invoke command:

python setup.py install

To checking the installation you can use to call ytrss. Unittest can be also helpful with verification.

Other information#

For more information about installation, configuration and bash completion read the documentation.

Author#

Rafal Kobel rafalkobel@rafyco.pl

Fast start#

tl;dr#

Install program
Prepare configuration file
Start ytrss client or configure docker
[Optional] Share your files into external server

How to start?#

First of all you need to prepare configuration file, which helps you describe all the sources that you want to subscribe and destinations where movies should be downloaded. See configuration to more information.

Next you should run a ytrss client to store information about new episodes and share it into described destinations. You can use:

ytrss run

or if you want that the program not stop after one execution and run forever, use:

ytrss daemon

After that you need to share generated podcast on your private http server.

Remember that this library have no secure podcast file from other viewers. You public it on your own responsibility. Please make sure that author of your favorite movies allows you to make podcast from his files.

A good idea is to use docker instead of system installation. It is cleaner and allows to better configuration. See: docker documentation

Configuration#

Configuration file#

The behaviour of the program you can define in configuration file. It tells what sources should be checked for new files and where will be saved or how to distribute them. The configuration file is a simple yaml (or json) file that named: config.yml (or config.json for json).

Localization#

The ytrss looking for following directory to find this file and get first available to work with.

From location defined in PYTHON_YTRSS_CONFIG environment.
For windows from $HOME\\YTRSS file
For linux in ~/.config/ytrss or /etc/ytrss/ file.

User also can set specific configuration file by define it with -c or --conf parameter in terminal client

Example configuration file#

The configuration file has yaml format. The example of the file looks like this:

---
url_prefix: https://my.domain/ytdown
storage: /home/user/podcasts/ytdown
subscriptions:
  - name: Private playlist
    url: https://youtube.com/playlist?list=<playlist_id>
    destination: default
  - name: YouTube
    destination: youtube
    url: https://www.youtube.com/@YouTube
destinations:
  default:
    title: Youtube - podcast
    author: youtube
    link: https://youtube.com
    desc: My favourite movies from YouTube
    img: https://www.youtube.com/yts/img/yt_1200-vfl4C3T0K.png
    directory: default

  youtube:
    title: Youtube channel
    author: youtube
    link: https://youtube.com
    desc: YouTube channel
    img: https://www.youtube.com/yts/img/yt_1200-vfl4C3T0K.png
    directory: youtube

Main structure#

Configuration keys#
key		default value	description
subscriptions	required	-	List of sources that will be look for new files. See Subscriptions structure.
destinations	required	-	A list of elements where the files should be placed. See Destinations structure.
config_dir	optional	`~/.config/ytrss` for unix or `~\\YTRSS` for windows	Directory where the configuration should be places
cache_path	optional	`<config_dir>/cache`	A place where all file should be downloaded before copy to destination
arguments	optional	[]	A list of parameters that are added to `youtube_dl` command
url_prefix	optional	http://localhost	A default url that is add to podcast address
storage	optional	~/podcasts	A place with all subscriptions
webhooks	optional	[]	A list of webhooks (name: url) Webhooks

Subscriptions structure#

Subscriptions structure#
key		default value	description
name	optional	“<unknown>”	Readable name of source
url	required	-	A localization of source (e.x. url to youtube channel)
destination	optional	“default”	The destination where the file will be transfer. See Destinations structure.
enable	optional	`True`	If set to `False` the source won’t be used

Destinations structure#

Destination structure#
key		default value	description
type	optional	rss	Type of destination (e.x. rss for podcast)
title	optional	“unknown title”	Title of podcast
url_prefix	optional	(empty)	a string that have been added to podcast url
author	optional	“Nobody”	Author of podcast
link	optional	“http://youtube.com”	List to podcast (e.x. to youtube channel)
desc	optional	“No description”	Description of podcast
img	optional	None	Optional url to podcast image
path	optional	-	Full path that the file should be saved (cannot be used with ‘directory’ option)
directory	optional	-	A directory to store files in storage destinaltion (cannot be used with ‘path’ option)
filters	optional	limit: 20	An object with rules what files should be delete Filters

Filters#

Filter is a mechanism that tells software when movies can be deleted

We support following values:

Filters#
key	default value	description
limit	20	A count of movies that can be stored for one destination

warn:: The movie are deleted after downloaded.

Terminal client#

ytrss is a command-line program that allows managing the process of downloading movies and generating podcasts based on a configuration file. It also handles the removal of files that are older than the specified item limit.

The ytrss utility is a powerful tool designed to manage the ytrss package, allowing users to track, generate, and download content based on specified sources.

Usage#

The basic syntax for the command is:

ytrss [OPTIONS] COMMAND [ARGS]...

More information about available commands you can search using –help argument.

$ ytrss --help
usage: ytrss [-h] [-c FILE] [-d]
             {help,version,run,daemon,clean,generate,configuration,download,url}
             ...

command line tool to manage ytrss package

options:
  -h, --help            show this help message and exit
  -c FILE, --conf FILE  configuration file
  -d, --debug-log       Enable debug logging

commands:
  Use once of this commands

  {help,version,run,daemon,clean,generate,configuration,download,url}
    help                Print help message
    version             Show version of this program
    run                 Find movie from sources and download
    daemon              Run downloading in loop mode
    clean               Clean all unnecessary files.
    generate            Generate elements in destinations.
    configuration       Print configuration
    download            Immediately download a movie to current location.
    url                 Add url to download

Global Options#

Option	Description
-h, –help	Show the help message and exit.
-c FILE, –conf FILE	Path to the configuration file to be used.
-d, –debug-log	Enable verbose debug logging for troubleshooting.

Commands#

You must use one of the following commands to interact with the package:

help#

Print the help message and exit.

version#

Show the current version of the ytrss program.

run#

Scans defined sources for new movies based on the configuration file. It attempts to download new content as well as any items that failed in previous attempts.

Upon a successful download, it:

Generates updated podcast files (feeds) for the corresponding source.
Rotates files by deleting the oldest movies if the predefined limit of elements is exceeded.

daemon#

Executes the run command periodically at one-hour intervals.

This command blocks the output until interrupted (e.g., via Ctrl+C).

Designed for automation and is the primary entry point when running within a Docker container.

clean#

Manually triggers the cleanup process to remove movies that are older than the specified limit.

generate#

Refreshes podcast files in the destination directories if changes have occurred, or generates them from scratch if they do not yet exist.

configuration#

Prints the current active configuration to the console for verification.

download#

Immediately attempts to download a specific movie provided as a parameter using built-in mechanisms. The file is saved directly into the directory from which the program was invoked.

url#

Adds a specific movie URL to the download queue.

The movie will be automatically processed and downloaded during the next run or daemon cycle.

By default, it is assigned to the “default” destination, which can be overridden via command arguments.

Examples#

Display Configuration:

ytrss configuration

Run in Debug Mode:

ytrss -d run

Using a Specific Config File:

ytrss --conf ./my_config.yaml generate

Add new url to download queue

ytrss url "https://yoututbe.com?watch=fdasdfas"

Warning

Before using the client, ensure that the configuration is set appropriately to customize the client’s behavior according to your preferences.

Webhooks#

Overview#

Webhooks allow external services to be notified automatically when specific events occur within the application. When a triggered action takes place, the application performs an HTTP GET request to a pre-configured URL.

Information about the event is passed directly in the URL via GET query parameters. This enables real-time integration with third-party scripts, automation tools, or monitoring services without the need for constant polling.

Configuration#

All webhook URLs must be defined in the application configuration file. Users can specify which URL should be called for each specific event type. If a URL is not provided for a particular hook in the config, that webhook will remain inactive.

Available Webhooks#

The following table lists all supported webhooks, their triggers, and the parameters available for use in the query string:

Webhook Name	Trigger Event	Available Parameters
start-daemon	Occurs when the application daemon starts up.	None
found-new-movie	Triggered when a new movie is discovered and identified.	title, url, id, desc, destination
start-downloading-movie	Triggered when the download process for a specific movie begins.	title, url, id, desc
success-download-movie	Occurs when a movie has been successfully downloaded.	title, url, id, desc
failed-download-movie	Triggered if an error occurs during the download process.	title, url, id, desc, cause

Parameter Definitions#

title: The title of the movie.

url: The source URL or link to the movie.

id: The unique internal identifier of the movie entity.

desc: The description or metadata associated with the movie.

destination: The intended storage path or category for the movie.

cause: A text message describing the error/exception that led to a download failure.

Docker#

This document provides instructions on how to containerize, run, and manage the ytrss application using Docker and Docker Compose.

Docker Hub Image#

The official Docker image is available and can be pulled directly from Docker Hub:

https://hub.docker.com/repository/docker/rafyco/ytrss/general

To pull the latest image, run:

docker pull rafyco/ytrss:latest

Running with Docker CLI#

To run the application as a standalone container, you can use the standard Docker build and run commands.

Build the image (Optional):#

If you prefer to build the image locally, navigate to the project root directory and run:

docker build -t ytrss-app:latest .

Run the container:#

Example command to start the application manually:

docker run -d \
--name ytrss \
-v $(pwd)/volumes/ytrss/config.yml:/home/ytrss/.config/ytrss/config/config.yml:ro \
-v $(pwd)/volumes/ytrss/podcasts:/home/ytrss/podcasts \
rafyco/ytrss:latest

Using Docker Compose#

For a production-like setup involving automatic video downloading, podcast generation, and a local web server to host the files, use the provided docker-compose.yml configuration.

Deployment Scenario#

The following configuration sets up two services:

ytrss: The core application that fetches videos and converts them into podcasts.
webserver: A lightweight static website server (based on lipanski/docker-static-website) that exposes the generated podcasts to your local network.

version: "3.8"
services:
  ytrss:
    build: .
    container_name: ytrss
    user: 1000:1000
    restart: always
    volumes:
      - ./volumes/ytrss/cache:/home/ytrss/.config/ytrss/cache
      - ./volumes/ytrss/config.yml:/home/ytrss/.config/ytrss/config/config.yml:ro
      - ./volumes/ytrss/database:/home/ytrss/.config/ytrss/database
      - ./volumes/ytrss/podcasts:/home/ytrss/podcasts

  webserver:
      image: lipanski/docker-static-website:latest
      restart: always
      ports:
        - "8080:3000"
      volumes:
        - ./volumes/ytrss/podcasts:/home/static/ytdown:ro
      depends_on:
        - ytrss
      networks:
        - ytrss_network
networks:
  ytrss_network:
    driver: bridge

How to run#

To start the entire stack in detached mode, run:

docker-compose up -d

The podcast feed will be available in your local network at http://<your-ip>:8080/ytdown/.

Volume Mapping Details#

The application relies on persistent volumes to maintain state and efficiency. Below are the descriptions of the mapped paths:

Cache Directory

Host Path: ./volumes/ytrss/cache
Container Path: /home/ytrss/.config/ytrss/cache
Description : Stores temporary segments of videos during the download process. Using a persistent volume here prevents data loss for partially downloaded files if the container restarts.

Configuration File

Host Path: ./volumes/ytrss/config.yml
Container Path: /home/ytrss/.config/ytrss/config/config.yml
Description: The main config.yml file for the program. It is mounted as Read-Only (:ro) to ensure the container does not modify your source configuration accidentally.

Database

Host Path: ./volumes/ytrss/database
Container Path: /home/ytrss/.config/ytrss/database
Description: Stores metadata and the history of downloaded files. This prevents the application from re-downloading videos that have already been processed.

Podcast Storage

Host Path: ./volumes/ytrss/podcasts
Container Path: /home/ytrss/podcasts
Description: The final destination for downloaded media and generated XML podcast feeds. This folder is shared with the webserver service so it can be accessed via a browser or podcast player.

User Permissions#

Note that the ytrss service runs with user: 1000:1000. Ensure that the directories created on the host machine within the ./volumes/ path have the appropriate ownership or write permissions for this UID/GID to avoid “Permission Denied” errors.

Testing & Quality Assurance#

This project uses tox to automate testing and ensure code consistency. Tox creates isolated virtual environments for each task, ensuring that tests run in a clean, reproducible environment.

Prerequisites#

Before running the suite, ensure you have the following installed:

Python 3.10+
tox: Install via pip: pip install tox
Docker: Required only for the megalinter environment.

Quick start#

To run the entire testing pipeline (Style, Typing, Unittests, Documentation, and Execution checks):

tox

To run specific environment:

tox -e <env_name>
# Example: tox -e unittests

Available Environments#

Available environments#
Command	Environment	Purpose
tox -e style	Linter	Runs pycodestyle and pylint to check for PEP 8 compliance.
tox -e typing	Static Analysis	Uses mypy for strict type checking to catch bugs before runtime.
tox -e unittests	Unit Testing	Runs all unittests in tests/unit using pytest.
tox -e integration	Integration	Runs integration tests in tests/integration to check module interaction.
tox -e documentation	Docs	Builds the project documentation via Sphinx.
tox -e execute	Smoke Test	Verifies the ytrss CLI tool installs and responds correctly.
tox -e megalinter	Deep Scan	Runs 70+ linters via Docker (useful before a major PR).

Changelog#

0.4#

0.4.0 #

Official docker support and docker-compose example
Autoclean old movies (limit destination)
Webhooks
Support for more sources url from yt-dlp
change downloading program from youtube_dl to yt-dlp
Drop support for python 3.7, 3.8 and 3.9
fixing documentation

0.3#

0.3.5 #

small documentation fixes

0.3.4 #

fix small bugs

0.3.3 #

fix small bugs

fix small bugs
new format of configuration (see: configuration)
new terminal tool (see: terminal)
support for all services from youtube_dl
locally download url
add url from console
auto made new configuration

0.2#

0.2.8 #

fix small bugs

0.2.6 #

Repair config files
Documentation in sphinx

0.2.5 #

fix small bugs

0.2.4 #

fix small bugs

0.2.3 #

fix small bugs

0.2.2 #

fix small bugs

0.2.1 #

Delete older files

0.2.0 #

Files download to specific directory
Read data of downloaded movie
Generate RSS channel for downloaded movie

0.1#

0.1.6 #

fix small bugs

0.1.5 #

Daemon for linux

0.1.4 #

Support for python3
Reduce commands to one prog

0.1.3 #

First working version.
Unit test.

0.1.2 #

fix small bugs

0.1.1 #

fix small bugs

0.1.0 #

fix small bugs

0.0#

0.0.5 #

fix small bugs

0.0.4 #

fix small bugs

0.0.3 #

fix small bugs

0.0.2 #

fix small bugs

0.0.1 #

fix small bugs

On this page