Skip to main content

Listen, monitor and archive your streams!

Project description


Listen, monitor and archive your streams!


If you need to listen or archive an Icecast stream, you will need ffmpeg:

sudo apt install ffmpeg

Install earhorn from pip (install the s3 extra to upload the segment to an s3 bucket):

pipx install earhorn
pipx install earhorn[s3]

You can start archiving an Icecast stream by providing a stream url and an archive path:

earhorn \
  --stream-url \

You can also start exporting the Icecast stats as prometheus metrics by providing an Icecast stats url:

earhorn \
  --stats-url \
  --stats-user admin \
  --stats-password hackme


docker pull


Usage: earhorn [OPTIONS]


  If a `.env` file is present in the current directory, it will be loaded and can be used to pass environment
  variables to this tool.


  The storage can be defined using a path to a local directory or an url to an s3 bucket. Segments will be saved on
  the storage you specified.

  To use an s3 bucket, you need to install the `s3` extras (`pip install earhorn[s3]`), use `s3://bucket-name` as
  value for the `--archive-path` option and export the s3 bucket credentials listed in the table below:

  | Variable                | Description                               | Example                     |
  | ----------------------- | ----------------------------------------- | --------------------------- |
  | AWS_ACCESS_KEY_ID       | The access key for your bucket user       | AKIA568knmklmk              |
  | AWS_SECRET_ACCESS_KEY   | The secret key for your bucket user       | mi0y84wu498zxsasa           |
  | AWS_S3_ENDPOINT_URL     | The endpoint to your s3 bucket (optional) | |
  | AWS_S3_REGION_NAME      | Region of your s3 bucket                  | us-east-2                   |

  Example: export AWS_S3_ENPOINT_URL=""


  To change the segments duration or format, see the ffmpeg documentation for details
  about the available options:

  --listen-port INTEGER           Listen port for the prometheus metrics endpoint.  [default: 9950]
  --hook PATH                     Path to a custom script executed to handle stream state `events`.
  --stats-url TEXT                URL to the icecast admin xml stats page.
  --stats-user TEXT               Username for the icecast admin xml stats page.  [default: admin]
  --stats-password TEXT           Password for the icecast admin xml stats page.
  --stream-url TEXT               URL to the icecast stream.
  --silence-detect-noise TEXT     Silence detect noise.  [default: -60dB]
  --silence-detect-duration TEXT  Silence detect duration.  [default: 2]
  --archive-path PATH             Path or url to the archive storage, supported storage are local filesystem and s3.
                                  If defined, the stream will be archived in the storage as segments.
  --archive-segment-filepath TEXT
                                  Archive segment filepath.  [default:
  --archive-segment-size INTEGER  Archive segment size in seconds.  [default: 3600]
  --archive-segment-format TEXT   Archive segment format.  [default: ogg]
  --archive-segment-format-options TEXT
                                  Archive segment format options.
  --archive-copy-stream           Copy the `stream` without transcoding (reduce CPU usage). WARNING: The stream has to
                                  be in the same format as the `--archive-segment-format`.
  --help                          Show this message and exit.


To develop this project, start by reading the Makefile to have a basic understanding of the possible tasks.

Install the project and the dependencies in a virtual environment:

make install
source .venv/bin/activate
earhorn --help

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

earhorn-0.20.2.tar.gz (27.1 kB view hashes)

Uploaded Source

Built Distribution

earhorn-0.20.2-py3-none-any.whl (29.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page