Initial release: Emby Media Player integration for Home Assistant

Features:
- Media player entities for active Emby client sessions
- Full playback control (play, pause, stop, seek)
- Volume control and mute/unmute
- Next/previous track navigation
- Media metadata display (title, artist, album, thumbnail)
- Media library browsing
- WebSocket for real-time state updates with polling fallback
- Config flow UI for easy setup
- HACS compatible

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,155 @@
+# Emby Media Player
+
+[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](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 > Expert > Advanced > Security)
+   - **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 **Expert** > **Advanced** > **Security**
+3. Click **Add** to create a new API key
+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.