haos-hacs-emby-media-player/README.md

Emby Media Player

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

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

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.