156 lines
4.6 KiB
Markdown
156 lines
4.6 KiB
Markdown
# Emby Media Player
|
|
|
|
[](https://github.com/hacs/integration)
|
|
|
|
A Home Assistant custom integration that exposes Emby media server clients as media players with full playback control, media metadata, and library browsing capabilities.
|
|
|
|
## Features
|
|
|
|
- **Media Player Control**: Play, pause, stop, seek, volume control, mute, next/previous track
|
|
- **Real-time Updates**: WebSocket connection for instant state synchronization with polling fallback
|
|
- **Media Metadata**: Display currently playing media information including:
|
|
- Title, artist, album (for music)
|
|
- Series name, season, episode (for TV shows)
|
|
- Thumbnail/artwork
|
|
- Duration and playback position
|
|
- **Media Browser**: Browse your Emby library directly from Home Assistant
|
|
- Navigate through Movies, TV Shows, Music libraries
|
|
- Play any media directly from the browser
|
|
- **Dynamic Session Discovery**: Automatically discovers and creates media player entities for active Emby clients
|
|
|
|
## Installation
|
|
|
|
### HACS (Recommended)
|
|
|
|
1. Open HACS in Home Assistant
|
|
2. Click on "Integrations"
|
|
3. Click the three dots menu and select "Custom repositories"
|
|
4. Add this repository URL and select "Integration" as the category
|
|
5. Click "Install"
|
|
6. Restart Home Assistant
|
|
|
|
### Manual Installation
|
|
|
|
1. Download the `custom_components/emby_player` folder
|
|
2. Copy it to your Home Assistant `custom_components` directory
|
|
3. Restart Home Assistant
|
|
|
|
## Configuration
|
|
|
|
1. Go to **Settings** > **Devices & Services**
|
|
2. Click **Add Integration**
|
|
3. Search for "Emby Media Player"
|
|
4. Enter your Emby server details:
|
|
- **Host**: Your Emby server hostname or IP address
|
|
- **Port**: Emby server port (default: 8096)
|
|
- **API Key**: Your Emby API key (found in Dashboard > Extended > API Keys)
|
|
- **Use SSL**: Enable if your server uses HTTPS
|
|
5. Select the Emby user account to use
|
|
6. Click **Submit**
|
|
|
|
### Getting an API Key
|
|
|
|
1. Open your Emby Server Dashboard
|
|
2. Navigate to **Extended** > **API Keys**
|
|
3. Click **New API Key** (+ button)
|
|
4. Give it a name (e.g., "Home Assistant")
|
|
5. Copy the generated key
|
|
|
|
## Options
|
|
|
|
After configuration, you can adjust the following options:
|
|
|
|
- **Scan Interval**: Polling interval in seconds (5-60, default: 10). Used as a fallback when WebSocket connection is unavailable.
|
|
|
|
## Supported Features
|
|
|
|
| Feature | Support |
|
|
|---------|---------|
|
|
| Play/Pause | Yes |
|
|
| Stop | Yes |
|
|
| Volume Control | Yes |
|
|
| Volume Mute | Yes |
|
|
| Seek | Yes |
|
|
| Next Track | Yes |
|
|
| Previous Track | Yes |
|
|
| Media Browser | Yes |
|
|
| Play Media | Yes |
|
|
|
|
## Entity Attributes
|
|
|
|
Each media player entity exposes the following attributes:
|
|
|
|
- `session_id`: Emby session identifier
|
|
- `device_id`: Device identifier
|
|
- `device_name`: Name of the playback device
|
|
- `client_name`: Emby client application name
|
|
- `user_name`: Emby user name
|
|
- `item_id`: Currently playing item ID
|
|
- `item_type`: Type of media (Movie, Episode, Audio, etc.)
|
|
|
|
## Automation Examples
|
|
|
|
### Dim lights when playing a movie
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "Dim lights for movie"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: media_player.emby_living_room_tv
|
|
to: "playing"
|
|
condition:
|
|
- condition: template
|
|
value_template: "{{ state_attr('media_player.emby_living_room_tv', 'item_type') == 'Movie' }}"
|
|
action:
|
|
- service: light.turn_on
|
|
target:
|
|
entity_id: light.living_room
|
|
data:
|
|
brightness_pct: 20
|
|
```
|
|
|
|
### Pause playback when doorbell rings
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "Pause Emby on doorbell"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: binary_sensor.doorbell
|
|
to: "on"
|
|
action:
|
|
- service: media_player.media_pause
|
|
target:
|
|
entity_id: media_player.emby_living_room_tv
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Issues
|
|
|
|
- Verify the Emby server is accessible from Home Assistant
|
|
- Check that the API key is valid and has appropriate permissions
|
|
- Ensure the port is correct (default is 8096)
|
|
|
|
### No Media Players Appearing
|
|
|
|
- Media player entities are only created for **active sessions** that support remote control
|
|
- Start playback on an Emby client and wait for the entity to appear
|
|
- Check the Home Assistant logs for any error messages
|
|
|
|
### WebSocket Connection Failed
|
|
|
|
If WebSocket connection fails, the integration will fall back to polling. Check:
|
|
- Firewall rules allow WebSocket connections
|
|
- Reverse proxy is configured to support WebSocket
|
|
- Server logs in Home Assistant for specific errors
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please open an issue or submit a pull request.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License.
|