Apple Media Remote (for HomePod, Apple TV, etc)

## Setup Notes

- pyatv has a compatibility issue with Python 3.14+. Use `--python python3.13` (or any version ≤3.13) when installing.
- If `~/.local/bin` isn't on your PATH after install, run: `pipx ensurepath`
- If your default Python is 3.14+, you can also call directly: `python3.13 -m pyatv.scripts.atvremote <command>`

## Scan for Devices

```bash
atvremote scan
atvremote --scan-hosts 10.0.0.50 scan          # Scan specific IP (faster)
atvremote --scan-hosts 10.0.0.50,10.0.0.51 scan  # Multiple IPs
```

Returns all discoverable Apple TV, HomePod, and AirPlay devices on the local network with their names, addresses, protocols, and pairing status.

## Target a Device

Use `-n <name>` (device name), `-s <ip>` (address), or `-i <id>` (identifier) to target:
```bash
atvremote -n "Kitchen" <command>
atvremote -s 10.0.0.50 <command>
atvremote -i AA:BB:CC:DD:EE:FF <command>
```

## Playback Control

```bash
atvremote -n "Kitchen" playing           # Now playing info (title, artist, album, position, etc.)
atvremote -n "Kitchen" play              # Resume playback
atvremote -n "Kitchen" pause             # Pause playback (resumable with play)
atvremote -n "Kitchen" play_pause        # Toggle play/pause
atvremote -n "Kitchen" stop              # Stop playback (ends session, cannot resume)
atvremote -n "Kitchen" next              # Next track
atvremote -n "Kitchen" previous          # Previous track
atvremote -n "Kitchen" skip_forward      # Skip forward (~10-30s, app-dependent)
atvremote -n "Kitchen" skip_backward     # Skip backward (~10-30s, app-dependent)
atvremote -n "Kitchen" skip_forward=30   # Skip forward specific seconds
atvremote -n "Kitchen" set_position=120  # Seek to position (seconds)
atvremote -n "Kitchen" set_shuffle=Songs # Shuffle: Off, Songs, Albums
atvremote -n "Kitchen" set_repeat=All    # Repeat: Off, Track, All
```

## Volume

```bash
atvremote -n "Kitchen" volume            # Get current volume (0-100)
atvremote -n "Kitchen" set_volume=50     # Set volume (0-100)
atvremote -n "Kitchen" volume_up         # Step up (~2.5%)
atvremote -n "Kitchen" volume_down       # Step down (~2.5%)
```

## Streaming

Stream local files or URLs to a device:
```bash
atvremote -n "Kitchen" stream_file=/path/to/audio.mp3   # Local file
atvremote -n "Kitchen" play_url=http://example.com/stream.mp3  # Remote URL
```

Supports common audio formats (MP3, WAV, AAC, FLAC, etc.).

## Power Management

```bash
atvremote -n "Apple TV" power_state      # Check power state
atvremote -n "Apple TV" turn_on          # Wake device
atvremote -n "Apple TV" turn_off         # Sleep device
```

## Navigation (Apple TV)

```bash
atvremote -n "Apple TV" up               # D-pad up
atvremote -n "Apple TV" down             # D-pad down
atvremote -n "Apple TV" left             # D-pad left
atvremote -n "Apple TV" right            # D-pad right
atvremote -n "Apple TV" select           # Press select/enter
atvremote -n "Apple TV" menu             # Back/menu button
atvremote -n "Apple TV" home             # Home button
atvremote -n "Apple TV" home_hold        # Long press home (app switcher)
atvremote -n "Apple TV" top_menu         # Go to main menu
atvremote -n "Apple TV" control_center   # Open control center
atvremote -n "Apple TV" guide            # Show EPG/guide
atvremote -n "Apple TV" channel_up       # Next channel
atvremote -n "Apple TV" channel_down     # Previous channel
atvremote -n "Apple TV" screensaver      # Activate screensaver
```

## Keyboard Input (Apple TV)

When a text field is focused:
```bash
atvremote -n "Apple TV" text_get                 # Get current text
atvremote -n "Apple TV" text_set="search query"  # Replace text
atvremote -n "Apple TV" text_append=" more"      # Append text
atvremote -n "Apple TV" text_clear               # Clear text
```

## App Control (Apple TV)

```bash
atvremote -n "Apple TV" app_list                          # List installed apps
atvremote -n "Apple TV" launch_app=com.apple.TVMusic      # Launch by bundle ID or URL
```

## Output Devices (Multi-room)

Manage connected audio outputs (e.g. grouping HomePods):
```bash
atvremote -n "Apple TV" output_devices                    # List current output device IDs
atvremote -n "Apple TV" add_output_devices=<device_id>    # Add speaker to group
atvremote -n "Apple TV" remove_output_devices=<device_id> # Remove from group
atvremote -n "Apple TV" set_output_devices=<device_id>    # Set specific output(s)
```

## Push Updates (Live Monitoring)

Watch for real-time playback changes:
```bash
atvremote -n "Kitchen" push_updates   # Prints updates as they occur (ENTER to stop)
```

## Pairing

Some devices (especially Apple TV) require pairing before control:
```bash
atvremote -n "Living Room" pair                   # Pair (follow PIN prompt)
atvremote -n "Living Room" --protocol airplay pair  # Pair specific protocol
atvremote wizard                                  # Interactive guided setup
```

Credentials are stored automatically in `~/.pyatv.conf` after pairing.

## Device Info

```bash
atvremote -n "Kitchen" device_info       # Model, OS version, MAC
atvremote -n "Kitchen" features          # List all supported features
atvremote -n "Kitchen" app               # Current app playing media
```

## Tips

- **Pause vs Stop:** Use `pause`/`play` to suspend and resume. `stop` ends the session entirely — playback must be restarted from the source (Siri, Home app, etc.)
- HomePods with "Pairing: NotNeeded" can be streamed to immediately
- Apple TVs typically require pairing first (all protocols the device supports)
- The `playing` command shows media type, title, artist, position, shuffle/repeat state
- For stereo HomePod pairs, target either unit by name
- Use `--scan-hosts` for faster targeting when you know the device IP
- Navigation and keyboard commands are primarily for Apple TV (not HomePod)