YTRSS - automatic podcast maker#

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

https://img.shields.io/badge/author-Rafa%C5%82%20Kobel-blue.svg 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/pypi/v/ytrss.svg 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:

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

https://img.shields.io/static/v1.svg?label=Linkedin&message=Rafal%20Kobel&color=blue&logo=linkedin https://img.shields.io/static/v1.svg?label=Github&message=rafyco&color=blue&logo=github https://img.shields.io/static/v1.svg?label=Facebook&message=Rafal%20Kobel&color=blue&logo=facebook

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.

  1. From location defined in PYTHON_YTRSS_CONFIG environment.

  2. For windows from $HOME\\YTRSS file

  3. 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

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.

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

0.3.2#

0.3.1#

0.3.0#

Warning

This version has different configuration file format and terminal client. You can’t use configuration from previous version. Please read documentation and update it.

  • 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

Fork me on GitHub
On this page