palmware/reference_recorder repository overview

⁠Palm Reference Recorder (PRR)

Docker based recorder for audio streams. PRR builds a configurable folder structure and filenames based on time. It starts recording, and stops itself at the next set time interval. The docker host will then restart the process, and a new file is started. At each startup, files older than x days are deleted.

PRR does not contain any GUI to browse recorded files. This can be accomplished with another docker container, for example filebrowser⁠, or by simply using the host's file browser.

Please note: PRR requires basic knowledge about Docker, and an installed Docker host. If you are not familiar with Docker and not willing to learn, then PRR is not for you.

For a quick start, skim through this text down to the filebrowser example⁠

⁠Setup

PRR is configured with environment variables. It has defaults for most settings, but you need to specify the stream to record by setting the URI variable.

Variables can be set when starting the container with docker run or with docker-compose. Some examples are at the end of this document.

The container should be set to restart always, or unless-stopped, as it is the docker host that recreates and starts a new recording on each interval.

⁠Volumes and folders

PRR will record to a folder structure under /audio in the container. You have to create a docker volume that mounts to /audio, or the files will be lost forever. For simplicity on a basic setup, bind mount⁠ a host folder.

On each startup, files in the base folder older than a set number of days are deleted.

⁠Running on Linux

Use docker-ce. On some distributions, installing docker with the system package manager gives an old version. See the Docker docs⁠ for various flavors.

⁠Environment Variables

All settings have default values, as below. You will have to set at least URI if you don't want to record BBC1.

• URI: Stream to record.

  URI=http://stream.live.vc.bbcmedia.co.uk/bbc_radio_one⁠

• FOLDER: Subfolder in the mounted volume.

  FOLDER=recordings

• FILE: How to create the recording filename under FOLDER. Uses python strftime⁠ format.
  The filename can include folders (like year or week number), and the full path will be created.

  FILE=%Y/%Y_%B/%Y_%b_%d/%Y%m%d_%H%M%S.mp3
  will record files like...
  /audio/recordings/2023/2023_January/2023_jan_04/20230104_140001.mp3

• LOGFILE: How to create the logging filename. The log will contain metadata and audio/silence.

  LOGFILE=%Y/%Y_%B/%Y_%b_%d/%Y%m%d.log

• BITRATE: Well... bitrate.

  BITRATE=64

• MAXAGE: Number of days to keep files. Older files in /audio/FOLDER are deleted on each restart

  MAXAGE=30

• LENGTH: How long files are recorded (minutes), 0-59
  A setting of 0 will restart the recorder at every hour. If the recorder is started at 13:42, the first file will be 18 minutes. The recorder will not append existing files. Make sure the filename includes at least seconds.

  LENGTH=0

• TZ: Time zone for file creation. Important - Use without quotes
  See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones⁠

  TZ=Europe/Stockholm

⁠Examples

⁠Using docker run (...nah...)

• Create a folder for the audio files. For example D:\Data\audio

• Open a command window (cmd.exe, terminal) and run docker:

  docker run --mount type=bind,source=D:\Data\audio,target=/audio --restart always -e MAXAGE=60   
    -e URI=http://stream.live.vc.bbcmedia.co.uk/bbc_radio_one palmware/reference_recorder
  

  Copy

  -e URI=http://stream.live.vc.bbcmedia.co.uk/bbc_radio_one for your source audio stream.
  -e MAXAGE=60 to delete files older than 60 days.
  --mount type=bind,source=D:\Data\audio,target=/audio to point the container's /audio to the host's folder.
  --restart always create new files continuously
  -d to run in background
  palmware/reference_recorder to specify the image to fetch from Docker Hub.

⁠Using Docker-Compose (...yes!)

• Create a new folder for the recorder. For example D:\Data\Recorder

• Create a subfolder called audio. With the above example: D:\Data\Recorder\audio

• In the recorder folder, create a text file called docker-compose.yml
  Example docker-compose.yml:

  version: "3"
  services:
    my_recorder:
      image: palmware/reference_recorder
      restart: unless-stopped
      environment:
        - URI=http://stream.live.vc.bbcmedia.co.uk/bbc_radio_one
        - BITRATE=32
        - FOLDER=bbc
        - MAXAGE=200
        - TZ=Europe/London
      volumes:
        - ./audio:/audio
  

  Copy

• Navigate to the recorder folder in a command window (cmd.exe, terminal).

• Run docker-compose up -d This will start a container in the background.

⁠Handling running containers

The recorder preferably runs in the background.
Please study the docker documentation on how to manage running containers.
Notable commands are docker-compose down and docker-compose up --build -d.
For a beginner, using Docker Desktop⁠ makes life easier.
For controlling a linux system, look at Portainer⁠
Also use Docker Desktop to inspect output if something goes wrong.

⁠Multiple recorders

To record more than one stream, start multiple recorders.
Use docker-compose to add extra recorder services, and add one filebrowser for the whole system if necessary.

⁠Multiple bitrates

For more than one quality, also start multiple recorders.
One with a high bitrate and a short maxage. One with a low bitrate and a high maxage.
Point their folder settings to something like "high" and "low" respectively.

⁠Filebrowser

To download and listen to the recordings, simply browse them on the docker host.

A very nice option is to run a docker container with a web based file browser. With docker-compose, the file browser is started together with the recorder. You will only need one file browser even if you run several recorder containers.

Please see docs for filebrowser⁠.

⁠Filebrowser example

• Follow the steps for a Docker Compose setup above.

• Create another subfolder, filebrowser

• In the filebrowser folder, create an empty file called filebrowser.db

  • On Windows, add an empty text file. Rename it, including the extension. Or open a command promt (cmd.exe) and use call > filebrowser.db
  • On Linux/Mac, use touch filebrowser.db

• Add the filebrowser service to docker-compose.yml:

  version: "3"
  services:
    bbc_radio_one:
      image: palmware/reference_recorder
      restart: unless-stopped
      environment:
        - URI=http://stream.live.vc.bbcmedia.co.uk/bbc_radio_one
      volumes:
        - ./audio:/audio
  
    filebrowser:
        image: filebrowser/filebrowser
        ports:
          - 8081:80
        volumes:
          - ./audio:/srv
          - ./filebrowser/filebrowser.db:/database.db
  

  Copy

• Run docker-compose up -d to start both services in the background.

The file browser should now be available on port 8081. http://localhost:8081⁠
For access from another machine, use the docker host's name or ip. http://server-name:8081⁠
Change port 8081 if necessary. Check firewall rules to allow access.

On first start, the filebrowser login is user:admin, password: admin
From the filebrowser GUI, you can change the password and add new users.

⁠Additional features

Suggestions are welcome, but this project was intended as an as-simple-as-possible solution.
Mp3 was chosen for its general compatibility, but other formats are certainly possible.
It is possible to record straight from ip audio sources like AES67, Ravenna, Axia etc. Please contact the maintainer for such 'plus' options.

⁠Acknowledgements

PRR uses GStreamer⁠, Python 3⁠ and Alpine Linux⁠ on Docker⁠.