# Remote control — sending a YouTube URL to Kodi

Kodi exposes a JSON-RPC HTTP endpoint that any client on the LAN can hit
to start playback. torttube wires up the `play` action so this works
out of the box once the addon is installed.

## Endpoint

```
POST http://<kodi-host>:8080/jsonrpc
Authorization: Basic base64(kodi:<password>)
Content-Type: application/json
```

Default Kodi user is `kodi`. The HTTP-control web server and a
password must be enabled via `Settings → Services → Control` before
JSON-RPC works.

## Play by YouTube ID

```bash
curl -u kodi:<pw> -H "Content-Type: application/json" \
  -X POST http://kodi-host:8080/jsonrpc -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "Player.Open",
    "params": {
      "item": {
        "file": "plugin://plugin.video.torttube/?action=play&id=dQw4w9WgXcQ"
      }
    }
  }'
```

## Play by full URL

```bash
curl -u kodi:<pw> -H "Content-Type: application/json" \
  -X POST http://kodi-host:8080/jsonrpc -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "Player.Open",
    "params": {
      "item": {
        "file": "plugin://plugin.video.torttube/?action=play&url=https%3A//www.youtube.com/watch%3Fv%3DdQw4w9WgXcQ"
      }
    }
  }'
```

The addon's `_extract_id()` accepts any of:
- bare 11-char ID
- `https://youtu.be/<id>`
- `https://www.youtube.com/watch?v=<id>`
- `https://www.youtube.com/shorts/<id>`
- `https://www.youtube.com/embed/<id>`
- `https://www.youtube.com/live/<id>`

## Android share-target wiring (later)

Future companion app (or HA automation) takes a YouTube URL from the
Android share sheet and posts it to whichever TV is selected. Until
that lands, any HTTP-capable client works (Kore, Yatse, curl, an HA
script, a phone shortcut, etc.).

## Common Kodi JSON-RPC ops you'll want

- `Player.Open` — start playback
- `Player.Stop` — stop
- `Player.PlayPause` — toggle
- `Player.Seek` — jump to position
- `Input.ShowOSD` — bring up the OSD
- `GUI.ShowNotification` — toast a message

Full docs: https://kodi.wiki/view/JSON-RPC_API