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

Claude Code Session Notes

This file documents mistakes and lessons learned during the development of this integration.

Mistakes Made

1. Missing /emby Prefix on API Endpoints

Problem: Initially created all API endpoints without the /emby prefix.

# Wrong
ENDPOINT_SYSTEM_INFO = "/System/Info"
ENDPOINT_USERS = "/Users"

# Correct
ENDPOINT_SYSTEM_INFO = "/emby/System/Info"
ENDPOINT_USERS = "/emby/Users"

Impact: Connection to Emby server failed with "cannot connect" errors.

Lesson: Always verify API endpoint formats against official documentation. Emby Server requires the /emby prefix for all API calls.

---

2. Incorrect Volume Control API Format

Problem: Tried multiple incorrect formats for the SetVolume command before finding the correct one.

# Attempt 1 - Wrong endpoint with body
endpoint = f"/Sessions/{session_id}/Command/SetVolume"
data = {"Arguments": {"Volume": 50}}

# Attempt 2 - Wrong: query parameter
endpoint = f"/Sessions/{session_id}/Command/SetVolume?Volume=50"

# Correct format
endpoint = f"/Sessions/{session_id}/Command"
data = {"Name": "SetVolume", "Arguments": {"Volume": "50"}}  # Arguments as STRINGS

Impact: Volume control didn't work even though mute/unmute worked fine.

Lesson: Emby general commands must be sent to /Command endpoint (not /Command/{CommandName}) with:

• Name field containing the command name
• Arguments as a dict with STRING values, not integers

---

3. NumberSelector Returns Float, Not Int

Problem: Home Assistant's NumberSelector widget returns float values, but port numbers must be integers.

# Wrong - port could be 8096.0
self._port = user_input.get(CONF_PORT, DEFAULT_PORT)

# Correct
self._port = int(user_input.get(CONF_PORT, DEFAULT_PORT))

Impact: Potential type errors or malformed URLs with decimal port numbers.

Lesson: Always explicitly convert NumberSelector values to the expected type.

---

4. Inconsistent Use of Constants

Problem: Hardcoded endpoint paths in some methods instead of using defined constants.

# Wrong - hardcoded
endpoint = f"/Sessions/{session_id}/Playing"

# Correct - using constant
endpoint = f"{ENDPOINT_SESSIONS}/{session_id}/Playing"

Impact: When the /emby prefix was added to constants, hardcoded paths were missed, causing inconsistent behavior.

Lesson: Always use constants consistently. When fixing issues, search for all occurrences of the affected strings.

---

5. Import Confusion Between Local and HA Constants

Problem: Initially imported CONF_HOST and CONF_PORT from homeassistant.const in some files, while also defining them in local const.py.

# Inconsistent imports
from homeassistant.const import CONF_HOST, CONF_PORT  # in __init__.py
from .const import CONF_HOST, CONF_PORT  # in config_flow.py

Impact: Potential confusion and maintenance issues, though values were identical.

Lesson: Choose one source for constants and use it consistently across all files. For custom integrations, prefer local constants for full control.

---

Best Practices Established

1. Test API endpoints with curl first - Verify the exact request format before implementing in code
2. Add debug logging - Include request URLs and response status codes for troubleshooting
3. Handle multiple API formats - Some servers may respond differently; implement fallbacks when sensible
4. Type conversion - Always explicitly convert UI input values to expected types
5. Consistent constant usage - Define constants once and use them everywhere
6. Wait for user approval before committing - Always let the user test changes before creating git commits