Spodcast

Spodcast is a caching Spotify podcast to RSS proxy. Using Spodcast you can follow Spotify-hosted netcasts/podcasts using any player which supports RSS, thus enabling the use of older hardware which is not compatible with the Spotify (web) app. Spodcast consists of the main Spodcast application - a Python 3 command line tool - and a PHP-based RSS feed generator. It uses the librespot-python library to access the Spotift API. To use Spodcast you need a (free) Spotify account. Spodcast only supports the Spotify podcast service, it does not interface with the music streaming service.

How does it work

Spotify hosts podcasts through their proprietary API and does not offer an RSS feed, making it mandatory to use the Spotify (web) app to follow these shows. This makes it impossible to follow Spotify-hosted shows on any device which does not support the Spotify (web) app. Spodcast solves this problem by creating an RSS feed out of data returned through the Spotify podcast API. This feed can be served by any web server which supports PHP. By running Spodcast through a task scheduler (cron on *nix, Task Scheduler on Windows) the feed will be kept up to date without the need for intervention. Have a look at these glorious ASCIIGraphs™ which should answer all unasked questions:

Spodcast regularly queries Spotify for new episodes...

                  --------------
                 |task scheduler|
                  --------------
                        |             ___________
  -------   APIv1   ----V---         /           \
 |Spotify|- - - - >|Spodcast|------>| File system |
  -------           --------         \___________/

You want to listen to an episode using your old, unsupported but still functional phone...

                                           _____         ............
   ___________          ----------        |     | . o O |bla bla bla.|
  /           \        |Web server|  RSS  | YOUR|        ````````````
 | File system |------>|  + PHP   |------>| OLD |
  \___________/         ----------        |PHONE|
                                          |_____|

Thus, by the simple expedient of using a piece of code which produces another piece of code which is used by yet another piece of code to speak to that old, creaky but still functional phone the latter is saved from early forced retirement. You can both feel virtuous for not adding another piece of waste to the pile, provident for not spending funds on a new device which does the same as the old one, smart for escaping the trap of planned obsolescence and whatever other emotion you prefer, including none whatsover.

Installation

Spodcast is available as an installable package on PyPi, just run:

$ pip install spodcast

...and you're set in case you only want to use Spodcast from your own account. Run this command as root to install it globally which makes it available to e.g. the web server user (www-data on Debian and derived distributions), this is necessary if you want to make use of the RSS feed service.

Spodcast can be installed from source by running pip install . (or pip install -e . if you want to be able to hack the code without needing to re-install after every change) from within the package root directory:

$ git clone https://github.com/Yetangitu/spodcast.git
$ cd spodcast
$ pip install .

Once installed this way it can be uninstalled using pip uninstall spodcast if so required. If you're planning to use the RSS proxy and web UI you need to make sure the spodcast command is available to the web server user.

Usage with Docker:

Pre-built images are available at Docker Hub. Refer to documentation below on how to build the image locally if that is desired.

A Note on Environment Variables:

The Spodcast images are built to either be configured exclusively through environment variables OR by passing arguments to the image -- if arguments are passed to the container any environment variables will be ignored.

Here is the list of permitted environment variables with a brief description:

| Variable | Default Value | Description | |----------|---------------|-------------| | SPOTIFY_PASSWORD | None | Spotify password | | SPOTIFY_USERNAME | None | Spotify username | | SPOTIFY_PODCAST_URLS | None | URLs of podcasts to download from spotify (separated by space) | | CRON_SCHEDULE | 0 0 * * Sun | Cron schedule for how often heywoodlh/spodcast-cron will attempt to download content from Spotify | | SPODCAST_ROOT | /data | Where all assets will go in the container filesystem | | SPODCAST_HTML | ${SPODCAST_ROOT}/html | Where HTML content will be places in container filesystem | | SPODCAST_CONFIG_JSON | ${SPODCAST_ROOT}/spodcast.json | Location of the spodcast config file | | SPOTIFY_CREDS_JSON | ${SPODCAST_ROOT}/creds.json | Location of the file containing Spotify credentials that Spodcast will use to continue logging in | | SPOTIFY_RC_PATH | ${SPODCAST_ROOT}/spotify.rc | Location of file containing creds to initially login | | MAX_EPISODES | 10 | Max amount of episodes to download per podcast | | LOG_LEVEL | info | Log level of Spodcast | | CHUNK_SIZE | 50000 | Download chunk size | | RSS_FEED | yes | Create an RSS feed for a web server | | TRANSCODE | no | Transcode to MP3 format (i.e. so iOS devices can play the audio files) | | LANGUAGE | en | Language of the content | | SKIP_EXISTING | yes | Do not re-download episodes that already exist on filesystem |

SPOTIFY_PASSWORD, SPOTIFY_USERNAME, and SPOTIFY_PODCAST_URLS are the only ones that are absolutely required -- everything else has a default value that is considered sane that it will fall back to if left undefined.

Usage with Docker-Compose and environment variables:

The following docker-compose.yml (also available at docker/docker-compose.yml) should work to easily deploy Spodcast, a web server and PHP server:

services:
  spodcast-cron:
    image: heywoodlh/spodcast-cron:latest
    volumes:
      - spodcast_data:/data
    restart: unless-stopped
    environment:
      - CRON_SCHEDULE=0 * * * *
      - SPOTIFY_PODCAST_URLS=https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk
      - SPOTIFY_PASSWORD=myawesomepassword
      - SPOTIFY_USERNAME=email@awesome.com
      - MAX_EPISODES=1
      
  spodcast-php:
    image: php:7-fpm
    volumes:
      - spodcast_data:/data
    restart: unless-stopped
    user: "101:101"
    networks:
    - spodcast

  spodcast-web:
    image: heywoodlh/spodcast-web:latest
    volumes:
      - spodcast_data:/data
    restart: unless-stopped
    networks:
    - spodcast
    ports:
      - 8080:80

networks:
  spodcast:
volumes:
  spodcast_data:

*Note: if this is the first time running Spodcast, the web server will error out with a 404. That is due to no HTML content having been setup by Spodcast yet. When running this the first time, it would be recommended to set CRON_SCHEDULE to something a bit more aggressive like * * * * * so that way episodes will be downloaded every minute and then once the initial HTML content has been populated change the CRON_SCHEDULE to something less aggressive.

Using the Docker CLI and supplying arguments:

Prepare spodcast directory (this example assumes you will store Spodcast's data in /tmp/spodcast):

mkdir -p /tmp/spodcast

echo 'spotify_username spotify_password' > /tmp/spodcast/spotify.rc

Login to Spotify and configure spodcast initially:

docker run -it -v /tmp/spodcast:/data heywoodlh/spodcast -c /data/spodcast.json --root-path /data/html --log-level info --credentials-location /data/creds.json -p -l /data/spotify.rc

Now run spodcast (this example will download The Joe Rogan Experience to /tmp/spodcast/html on the Docker host):

docker run -it -v /tmp/spodcast:/data heywoodlh/spodcast -c /data/spodcast.json --log-level info --max-episodes 10 'https://open.spotify.com/show/4rOoJ6Egrf8K2IrywzwOMk'

Build the image locally:

If you would prefer to build the image locally:

git clone https://github.com/Yetangitu/Spodcast && cd Spodcast

docker build -t spodcast -f docker/Dockerfile .

Docker usage will be exactly the same as the examples above with the exception that you will want to replace the heywoodlh/spodcast image with spodcast.

Usage

To use Spodcast you need a (free) Spotify account, if you don't have one yet you'll need to take care of that first at https://www.spotify.com/signup/ . If you plan to use the RSS proxy feature you'll also need a web server to serve the RSS feed(s), any server which supports PHP will do here. See Web server requirements for more information on how to configure the server.

Here's spodcast displaying its help message:

$ spodcast -h
usage: spodcast [-h] [-c CONFIG_LOCATION] [-p] [-v] [-l LOGIN] [--root-path ROOT_PATH]
                [--skip-existing SKIP_EXISTING] [--retry RETRY] [--max-episodes MAX_EPISODES]
                [--chunk-size CHUNK_SIZE] [--download-real-time DOWNLOAD_REAL_TIME]
                [--language LANGUAGE] [--credentials-location CREDENTIALS_LOCATION]
                [--rss-feed RSS_FEED] [--transcode TRANSCODE] [--log-level LOG_LEVEL]
                [urls ...]

A caching Spotify podcast to RSS proxy.

positional arguments:
  urls                  Download podcast episode(s) from a url. Can take multiple urls.

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG_LOCATION, --config-location CONFIG_LOCATION
                        Specify the spodcast.json location
  -p, --prepare-feed    Installs RSS feed server code in ROOT_PATH.
  -v, --version         show program's version number and exit
  -l LOGIN, --login L