====== mpv-control — API Reference ======

HTTP REST API served on port **3000**. All endpoints use the **GET** method — designed for easy integration with Node-RED HTTP request nodes.

Media directory: ''/home/er/media''

===== Media Files =====

==== GET /files ====

Returns a JSON tree of all supported media files in the media directory, including subdirectories (up to 5 levels deep).

**Response:**
<code javascript>
[
  {
    "name": "videos",
    "path": "/home/er/media/videos",
    "type": "directory",
    "children": [
      {
        "name": "intro.mp4",
        "path": "/home/er/media/videos/intro.mp4",
        "type": "video"
      }
    ]
  },
  {
    "name": "welcome.jpg",
    "path": "/home/er/media/welcome.jpg",
    "type": "image"
  }
]
</code>

**File types returned:** video (mp4, mkv, avi), image (jpg, jpeg, png, bmp), audio (mp3, wav).

===== Playback Control =====

==== GET /load?file=<path> ====

Loads a file into the player. The file is **paused by default** — call ''/play'' to start playback. This allows precise timing synchronization with other room events.

**Parameter:**
^ Name ^ Description ^
| file | Full path to the media file (as returned by ''/files'') |

**Example:**
<code>
GET /load?file=/home/er/media/videos/intro.mp4
</code>

==== GET /play ====

Starts or resumes playback of the currently loaded file.

==== GET /pause ====

Pauses playback. Resume with ''/play''.

==== GET /stop ====

Stops playback completely.

==== GET /forward ====

Seeks forward **10 seconds** in the current file.

==== GET /backward ====

Seeks backward **10 seconds** in the current file.

===== Web UI =====

==== GET / ====

Returns an HTML page with a file browser and playback controls. Intended for manual testing and setup — not for game operation.

===== Node-RED Usage =====

All endpoints are GET — use a standard HTTP request node in Node-RED:

<code>
[Inject: "/load?file=/home/er/media/intro.mp4"] → [HTTP Request: GET http://<ip>:3000{{payload}}]
[Inject: ""] → [HTTP Request: GET http://<ip>:3000/play]
</code>

**Typical flow:**
  - Load a file (paused)
  - Wait for the right moment in the game logic
  - Send ''/play'' to start playback
  - Send ''/stop'' when done (or let it finish)