Update README.md
This commit is contained in:
Lyfesaver
164
README.md
164
README.md
@@ -1,120 +1,86 @@
|
|||||||
# Dispatcharr Integration for Home Assistant
|
# Dispatcharr Integration for Home Assistant
|
||||||
|
|
||||||
[](https://github.com/custom-components/hacs)
|
This is a custom integration for Home Assistant that monitors active streams from a Dispatcharr server. It provides sensors to track the total number of streams and detailed information for each individual stream.
|
||||||
|
|
||||||
This is a custom integration for [Home Assistant](https://www.home-assistant.io/) that connects to your [Dispatcharr](https://github.com/Dispatcharr/Dispatcharr) instance. It provides real-time monitoring of active streams, creating dynamic sensors for each stream and a summary sensor for the total count.
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
* **Total Stream Count:** A dedicated sensor (`sensor.dispatcharr_total_active_streams`) that shows the total number of currently active streams.
|
- Provides a sensor showing the total number of active streams (`sensor.total_active_streams`).
|
||||||
|
- Dynamically creates a unique sensor for each active stream, which is automatically removed when the stream stops.
|
||||||
|
- Pulls detailed Electronic Program Guide (EPG) information for each active stream, including:
|
||||||
|
- Program Title
|
||||||
|
- Episode Title (Subtitle)
|
||||||
|
- Episode Number
|
||||||
|
- Description
|
||||||
|
- Start and End times
|
||||||
|
- Displays stream-specific details like client count, resolution, codecs, and bitrate as sensor attributes.
|
||||||
|
|
||||||
* **Dynamic Stream Sensors:** Creates a new sensor entity for each active stream automatically. These sensors are removed automatically when the stream stops, keeping your Home Assistant instance clean.
|
## Installation and Configuration
|
||||||
|
|
||||||
* **Rich Stream Data:** Each stream sensor provides detailed attributes, including:
|
### Installation
|
||||||
|
|
||||||
* Channel Name and Number
|
1. Copy the `dispatcharr_sensor` directory into your Home Assistant `<config>/custom_components/` directory.
|
||||||
|
2. Restart Home Assistant.
|
||||||
|
|
||||||
* Channel Logo URL
|
### Configuration
|
||||||
|
|
||||||
* Client Count
|
Configuration is done via the UI.
|
||||||
|
|
||||||
* Video Resolution, FPS, and Codec
|
1. Go to **Settings** > **Devices & Services**.
|
||||||
|
2. Click the **Add Integration** button in the bottom right.
|
||||||
|
3. Search for "Dispatcharr" and select it.
|
||||||
|
4. In the configuration dialog, enter the required information:
|
||||||
|
- **Host:** The IP address of your Dispatcharr server (e.g., `192.168.0.121`).
|
||||||
|
- **Port:** The port your Dispatcharr server is running on (e.g., `9191`).
|
||||||
|
- **Username:** Your Dispatcharr username.
|
||||||
|
- **Password:** Your Dispatcharr password.
|
||||||
|
|
||||||
* Audio Codec
|
## Sensors Provided
|
||||||
|
|
||||||
* Average Bitrate
|
### Total Active Streams Sensor
|
||||||
|
|
||||||
* **Live Program Information:** The integration parses your EPG data to display the currently airing program's title, description, start time, and stop time for each active stream.
|
A single sensor that provides a numeric count of the total active streams.
|
||||||
|
|
||||||
## Prerequisites
|
- **Entity ID:** `sensor.total_active_streams`
|
||||||
|
- **State:** A number representing the count of active streams (e.g., `2`).
|
||||||
|
|
||||||
* A running instance of [Dispatcharr](https://github.com/Dispatcharr/Dispatcharr).
|
### Individual Stream Sensors
|
||||||
|
|
||||||
* [Home Assistant Community Store (HACS)](https://hacs.xyz/) installed on your Home Assistant instance.
|
These sensors are created on-the-fly when a stream starts and are removed when it stops.
|
||||||
|
|
||||||
* The username and password for your Dispatcharr user account.
|
- **Entity ID:** Will be generated based on the channel name, like `sensor.dispatcharr_amc`.
|
||||||
|
- **State:** "Streaming"
|
||||||
|
- **Attributes:**
|
||||||
|
- `channel_number`: The channel number from the EPG guide (e.g., `102`).
|
||||||
|
- `channel_name`: The display name of the channel (e.g., `AMC`).
|
||||||
|
- `program_title`: The title of the currently airing program.
|
||||||
|
- `episode_title`: The title of the specific episode, if available.
|
||||||
|
- `episode_number`: The season/episode number (e.g., `S1E18`), if available.
|
||||||
|
- `program_description`: The description of the current program.
|
||||||
|
- `program_start`: The start time of the current program (ISO format).
|
||||||
|
- `program_stop`: The end time of the current program (ISO format).
|
||||||
|
- `clients`: The number of clients watching the stream.
|
||||||
|
- `resolution`: The resolution of the stream (e.g., `1280x720`).
|
||||||
|
- `fps`: The frame rate of the stream.
|
||||||
|
- `video_codec`: The video codec being used.
|
||||||
|
- `audio_codec`: The audio codec being used.
|
||||||
|
- `avg_bitrate`: The average bitrate of the stream.
|
||||||
|
|
||||||
## Installation via HACS
|
## Example Lovelace Card
|
||||||
|
|
||||||
This integration is not yet in the default HACS repository. You can add it as a custom repository.
|
|
||||||
|
|
||||||
1. In Home Assistant, go to **HACS** > **Integrations**.
|
|
||||||
|
|
||||||
2. Click the three dots in the top-right corner and select **"Custom repositories"**.
|
|
||||||
|
|
||||||
3. In the "Repository" field, enter the URL to this GitHub repository: `https://github.com/lyfesaver74/ha-dispatcharr`
|
|
||||||
|
|
||||||
4. For the "Category" dropdown, select **"Integration"**.
|
|
||||||
|
|
||||||
5. Click **"Add"**.
|
|
||||||
|
|
||||||
6. You should now see the "Dispatcharr Sessions Sensor" in your HACS integrations list. Click **"Install"** and proceed with the installation.
|
|
||||||
|
|
||||||
7. Restart Home Assistant when prompted.
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Once the integration is installed, you can add it to Home Assistant via the UI.
|
|
||||||
|
|
||||||
1. Go to **Settings** > **Devices & Services**.
|
|
||||||
|
|
||||||
2. Click the **"+ Add Integration"** button in the bottom right.
|
|
||||||
|
|
||||||
3. Search for **"Dispatcharr"** and select it.
|
|
||||||
|
|
||||||
4. A configuration dialog will appear. Enter the following information:
|
|
||||||
|
|
||||||
* **Host:** The IP address of your Dispatcharr server (e.g., `192.168.0.121`).
|
|
||||||
|
|
||||||
* **Port:** The port your Dispatcharr server is running on (default is `9191`).
|
|
||||||
|
|
||||||
* **Username:** Your Dispatcharr username.
|
|
||||||
|
|
||||||
* **Password:** Your Dispatcharr password.
|
|
||||||
|
|
||||||
5. Click **"Submit"**. The integration will be set up and your sensors will be created.
|
|
||||||
|
|
||||||
## Provided Sensors
|
|
||||||
|
|
||||||
The integration will create the following entities:
|
|
||||||
|
|
||||||
* **`sensor.dispatcharr_total_active_streams`**: A sensor that always exists and shows the total number of active streams. Its state is a number (e.g., `0`, `1`, `2`).
|
|
||||||
|
|
||||||
* **`sensor.dispatcharr_stream_<channel_name>`** (Dynamic): A new sensor will be created for each active stream. The entity ID is based on the channel name. For example, a stream of "BBC America" might create `sensor.dispatcharr_stream_us_bbc_america_hd`.
|
|
||||||
|
|
||||||
* The state of these sensors is either `Streaming` (when active) or `Idle` (if it persists briefly after stopping).
|
|
||||||
|
|
||||||
* These sensors will be removed automatically when no longer active.
|
|
||||||
|
|
||||||
### Stream Sensor Attributes
|
|
||||||
|
|
||||||
Each dynamic stream sensor will have the following attributes:
|
|
||||||
|
|
||||||
| Attribute | Description | Example |
|
|
||||||
|---|---|---|
|
|
||||||
| `channel_number` | The stream's channel number or ID. | `98209` |
|
|
||||||
| `channel_name` | The friendly name of the channel. | `US| BBC America ᴴᴰ` |
|
|
||||||
| `logo_url` | A direct URL to the channel's logo image. | `http://.../api/channels/logos/262/cache/` |
|
|
||||||
| `clients` | The number of clients watching this stream. | `1` |
|
|
||||||
| `resolution` | The current video resolution. | `1280x720` |
|
|
||||||
| `fps` | The current frames per second. | `59.94` |
|
|
||||||
| `video_codec` | The video codec being used. | `h264` |
|
|
||||||
| `audio_codec` | The audio codec being used. | `aac` |
|
|
||||||
| `avg_bitrate` | The average bitrate of the stream. | `4.11 Mbps` |
|
|
||||||
| `program_title` | The title of the currently airing program. | `Doctor Who` |
|
|
||||||
| `program_description` | A description of the current program. | `The Doctor travels through time...` |
|
|
||||||
| `program_start` | The start time of the current program. | `2025-10-02T14:00:00-05:00` |
|
|
||||||
| `program_stop` | The end time of the current program. | `2025-10-02T15:00:00-05:00` |
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
* **Program Data is `null`:** If your stream sensors are created but the `program_title`, `program_description`, etc., are `null`, it means the integration was unable to find matching guide data for that specific channel in your Dispatcharr EPG file. Please ensure that the channel has EPG data assigned within the Dispatcharr UI and that your EPG source has been recently refreshed.
|
|
||||||
|
|
||||||
* **Authentication Errors:** If you receive errors after setup, double-check that your Dispatcharr username and password are correct.
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
This project is licensed under the MIT License - see the `LICENSE` file for details.
|
|
||||||
```
|
|
||||||
|
|
||||||
|
You can use a Markdown card in your Home Assistant dashboard to display a clean summary of all active streams.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
type: markdown
|
||||||
|
title: Active Dispatcharr Streams
|
||||||
|
content: |
|
||||||
|
{% for stream in states.sensor | selectattr('attributes.channel_name', 'defined') | selectattr('entity_id', 'search', 'dispatcharr_') %}
|
||||||
|
**{{ stream.attributes.channel_name }} ({{ stream.attributes.channel_number }})**
|
||||||
|
*Now Playing:* {{ stream.attributes.program_title }}
|
||||||
|
{% if stream.attributes.episode_title %}
|
||||||
|
*Episode:* {{ stream.attributes.episode_title }} ({{ stream.attributes.episode_number }})
|
||||||
|
{% endif %}
|
||||||
|
*Clients:* {{ stream.attributes.clients }} | *Resolution:* {{ stream.attributes.resolution }}
|
||||||
|
***
|
||||||
|
{% else %}
|
||||||
|
No active streams.
|
||||||
|
{% endfor %}
|
||||||
|
|||||||
Reference in New Issue
Block a user