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:

[
  {
    "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).

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:

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

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:

[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:

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)

Table of Contents