Metadata-Version: 2.4
Name: earhorn
Version: 0.21.1
Summary: Listen, monitor and archive your streams!
Author-email: Joola <jooola@users.noreply.github.com>
License-Expression: GPL-3.0-only
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9.0,>=8.0.1
Requires-Dist: httpx<0.29,>=0.28.0
Requires-Dist: lxml<6.1,>=6
Requires-Dist: prometheus-client<0.23,>=0.22.1
Requires-Dist: pydantic<3.0,>=2.10.6
Requires-Dist: python-dotenv<2.0,>=1.0.0
Requires-Dist: typing-extensions>=4.2.0
Provides-Extra: dev
Requires-Dist: lxml-stubs<0.6,>=0.5.0; extra == "dev"
Requires-Dist: moto<6.0,>=5.0.0; extra == "dev"
Requires-Dist: mypy<2.0,>=1.0; extra == "dev"
Requires-Dist: pylint<4.0,>=3.0.0; extra == "dev"
Requires-Dist: pytest-cov<7.1,>=7; extra == "dev"
Requires-Dist: pytest-httpx<0.36,>=0.35.0; extra == "dev"
Requires-Dist: pytest-xdist<4.0,>=3.0.0; extra == "dev"
Requires-Dist: pytest<9.0,>=8.0.0; extra == "dev"
Requires-Dist: testcontainers<5.0,>=4.0.0; extra == "dev"
Requires-Dist: types-boto3<2.0,>=1.0.2; extra == "dev"
Provides-Extra: s3
Requires-Dist: boto3<2.0,>=1.24.8; extra == "s3"
Provides-Extra: sentry
Requires-Dist: sentry-sdk<2.38,>=2.37; extra == "sentry"
Dynamic: license-file

# earhorn

Listen, monitor and archive your streams!

[![](https://mermaid.ink/svg/pako:eNqNlD9PwzAQxb_KySNqFySWqCoDMLAw0AEhgiorvhIriV1dnAJCfHcuzj8nzsDmvHv383Muzo_IrEKRiNpJh_dafpCstpfr1AB4CVJxcJIc4AWNg1waVSKlAmTdGsgdB4k73q7eYbvdLwsx7Ey2QpdjU4ekQO06JkiADV0TWZ-O7aI-NlTCbpflVme436-DQnMCj35_V0PbqvCkDSq4jUN3ppU34AutfxZiSuy1BF4xTkwoq_9HHtx95vYxDj3ntr1ZjlnRi1GMVNy1ZSCsLD92ru50Yd9ablvEsUcEl06Wiq4QkhbHsYU_DQ90aGTsbZdwtlX3PoMzLOdT6tqhmY9m1CK3pCzXl7l71Lx7DLuGWhSnznCn58Z0eGqM0eZjGu0A84ioOtCW1X7pZb5rCTx8abe4X2gUIJElcHb10rLh6A1L4lRh8GCIRxC4nux88xepHfDU4YZtmTWqv96frE8Y3zFSPDQ2zJXoMxYbUSFVUiv-d_20DangT6jCVCS85Ashm9KlIjW_bG3OigM-KO0sieQkyxo3QjbOHr5NJhJHDQ6m_hfYu37_AFEs0XE)](https://mermaid.live/edit#pako:eNqNlD9PwzAQxb_KySNqFySWqCoDMLAw0AEhgiorvhIriV1dnAJCfHcuzj8nzsDmvHv383Muzo_IrEKRiNpJh_dafpCstpfr1AB4CVJxcJIc4AWNg1waVSKlAmTdGsgdB4k73q7eYbvdLwsx7Ey2QpdjU4ekQO06JkiADV0TWZ-O7aI-NlTCbpflVme436-DQnMCj35_V0PbqvCkDSq4jUN3ppU34AutfxZiSuy1BF4xTkwoq_9HHtx95vYxDj3ntr1ZjlnRi1GMVNy1ZSCsLD92ru50Yd9ablvEsUcEl06Wiq4QkhbHsYU_DQ90aGTsbZdwtlX3PoMzLOdT6tqhmY9m1CK3pCzXl7l71Lx7DLuGWhSnznCn58Z0eGqM0eZjGu0A84ioOtCW1X7pZb5rCTx8abe4X2gUIJElcHb10rLh6A1L4lRh8GCIRxC4nux88xepHfDU4YZtmTWqv96frE8Y3zFSPDQ2zJXoMxYbUSFVUiv-d_20DangT6jCVCS85Ashm9KlIjW_bG3OigM-KO0sieQkyxo3QjbOHr5NJhJHDQ6m_hfYu37_AFEs0XE)

## Install

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

```sh
sudo apt install ffmpeg
```

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

```sh
pipx install earhorn
pipx install earhorn[s3]
```

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

```sh
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:

```sh
earhorn \
  --stats-url https://stream.example.org/admin/stats.xml \
  --stats-user admin \
  --stats-password hackme
```

### Docker

```sh
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:

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