earhorn
Listen, monitor and archive your streams!
Install
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 https://stream.example.org/live.ogg \
--archive-path=/to/my/archive
You can also start exporting the Icecast stats as prometheus metrics by providing an Icecast stats url:
earhorn \
--stats-url https://stream.example.org/admin/stats.xml \
--stats-user admin \
--stats-password hackme
Docker
docker pull ghcr.io/jooola/earhorn
Usage
Usage: earhorn [OPTIONS]
ENVIRONMENT VARIABLES:
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.
ARCHIVE STORAGE:
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) | https://s3.nl-ams.scw.cloud |
| AWS_S3_REGION_NAME | Region of your s3 bucket | us-east-2 |
Example: export AWS_S3_ENPOINT_URL="https://s3.nl-ams.scw.cloud"
ARCHIVE SEGMENTS:
To change the segments duration or format, see the ffmpeg documentation for details
about the available options:
https://ffmpeg.org/ffmpeg-formats.html#segment_002c-stream_005fsegment_002c-ssegment
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:
{year}/{month}/{day}/{hour}{minute}{second}.{format}]
--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.
Developmement
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
1 maintainer
Metadata
1 maintainer
Release files for earhorn 0.22.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| earhorn-0.22.1.tar.gz | 28.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| earhorn-0.22.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 57.9 kB
Release files / earhorn-0.22.1.tar.gz
| Download URL | earhorn-0.22.1.tar.gz |
|---|---|
| Size | 28.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a16d14bc020ada50f69afe93685e543b19fcc61b78fa3b44eac6dd7965ec4f62
|
|
BLAKE2b-256 checksum How to use checksums |
57ecce662fbf522148e408429346431357c31ac3edce77487f6d87cb489851b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 13, 2026.
Transparency logRelease files / earhorn-0.22.1-py3-none-any.whl
| Download URL | earhorn-0.22.1-py3-none-any.whl |
|---|---|
| Size | 29.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c4be74e12900f3c70e69d650d992cf0de508be5aa9adb022af3fd40510dcb3a5
|
|
BLAKE2b-256 checksum How to use checksums |
6f770b788d764a05ac398d14e7c2e87ea5458d02562c3ea9482a46fda6ad57da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 13, 2026.
Transparency log
