Mediarss is a wrapper above [youtube-dl]( to periodically check if a list of media channels has new content available and automatically download it to a desired location with a specified format.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Lyz fd9b9b401b
Merge branch 'feat/add_max_file_size'
4 months ago
docs Use config file 11 months ago
mediarss Added max_file_size 4 months ago
tests Added max_file_size 4 months ago
.gitignore Added gitignore 11 months ago Updated changelog 4 months ago Added max_file_size 4 months ago
requirements.txt Process youtube-dl args 11 months ago Update version 10 months ago
tox.ini End first version 11 months ago


Mediarss is a wrapper above youtube-dl to periodically check if a list of media channels has new content available and automatically download it to a desired location with a specified format.


  • Periodically check if there is new content.
  • Download only new content.
  • Save files with a linux friendly name format.
  • Embed (when possible) metadata and thumbnails on the files.
  • Proxy support.

Supported sites

As a youtube-dl wrapper, it supports all the sites it does.

Nevertheless it’s been tested with:


Bandcamp is supported to download albums but not complete profiles, once the issue is closed it will be supported too.


Install the package

git clone
cd mediarss
pip install -r requirements.txt
python3 install


By default all configuration and user data will be at ~/.local/share/mediarss/.

Create the configuration file

Create the main configuration file in ~/.local/share/mediarss/config.yaml with the following contents:

download_path: '~/downloads'
feeds_path: '~/.local/share/mediarss/feeds.yaml'
download_archive: '~/.local/share/mediarss/download_archive.txt'
max_filesize: 12582912
  • download_path: Is the parent path where content will be downloaded. Mediarss will create a directory tree of media types, genres and artists.
  • feeds_path: Path to the feeds file.
  • download_archive: Path to the file saving what content has already been downloaded.
  • max_filesize: The maximum file size in bytes to be downloaded, if it’s greater it will be ignored.

Create the feeds file

Create the feeds file in ~/.local/share/mediarss/feeds.yaml with the following contents:

      playlist_end: 10
      recurrence: 30d

Where the first level is the media type, right now it only supports music, but in the future it can support images or video.

The second level is the genre, while the third is the artist.

The artist object has the following fields:

  • last_fetch: Must be left empty, the program will autocomplete it. It will use it to know if it has to try to download new content or not.
  • links: List of links from where the program will fetch the media.
  • playlist_end: Number of items to download from the links. mediarss wont download content that has already downloaded. Nevertheless it will try each of the links. If you have an artist that has 150 items, it will try all of them. With this parameter we limit the fetch to, for example, the first 10 items. The first time a feed is downloaded (last_fetch parameter is empty) it will ignore this parameter.
  • recurrence: With what periodicity does mediarss have to try to fetch new content. It can be a string with combination of (d)ays, (h)ours, (m)inutes, (s)econds, such as 20d 4h 20m 1s.

Create the archive file

In this archive mediarss will save all the content thas has already been downloaded.

touch ~/.local/share/mediarss/download_archive.txt


usage: mediarss [-h] [--config CONFIG] [--proxy PROXY] [-v | -q]

Autodownload media from streaming sites

optional arguments:
  -h, --help            show this help message and exit
  --config CONFIG, -c CONFIG
                        config.yaml location
  --proxy PROXY, -p PROXY
                        Specify proxy string, such as socks5://
  -v, --verbose
  -q, --quiet


To run the tests first install tox

pip3 install tox

And then run the tests



lyz at riseup