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

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

Response:

[
  {
    "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"
  }
]

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

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:

Example:

GET /load?file=/home/er/media/videos/intro.mp4

Starts or resumes playback of the currently loaded file.

Pauses playback. Resume with /play.

Stops playback completely.

Seeks forward 10 seconds in the current file.

Seeks backward 10 seconds in the current file.

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

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

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

Typical flow:

1. Load a file (paused)
2. Wait for the right moment in the game logic
3. Send /play to start playback
4. Send /stop when done (or let it finish)