Skip to main content

Listen, monitor and archive your streams!

Project description

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:

pip install earhorn

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]

  See the ffmpeg documentation for details about the `--archive-segment-*` 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`.
  --stream-url TEXT               URL to the icecast stream.
  --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.
  --archive-path PATH             Path to the archive storage directory. If defined, the archiver will save the
                                  `stream` in segments in the storage path.
  --archive-segment-size INTEGER  Archive segment size in seconds.  [default: 3600]
  --archive-segment-filename TEXT
                                  Archive segment filename (without extension).  [default: archive-%Y%m%d_%H%M%S]
  --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

Releases

To release a new version, first bump the version number in pyproject.toml by hand or by using:

# poetry version --help
poetry version <patch|minor|major>

Run the release target:

make release

Finally, push the release commit and tag to publish them to Pypi:

git push --follow-tags

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.11.0a1.tar.gz (23.5 kB view hashes)

Uploaded Source

Built Distribution

earhorn-0.11.0a1-py3-none-any.whl (24.4 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