Skip to content

Latest commit

 

History

History
786 lines (584 loc) · 13.2 KB

APIDESIGN.md

File metadata and controls

786 lines (584 loc) · 13.2 KB
Raw

Postman

You can download Postman collection and environment here

For safety reasons computer actions route not included!

Responses

Default response:

{ "message": "success or error message" }

API Routes

  • MPV Status
  • Playback controls
  • Playlist
  • Tracks
  • Filebrowser
  • Collection handling
  • Computer actions

Status

/api/v1/mpvinfo

Methods: GET

Gets info about MPV. MPV remote plugin settings also included.

/api/v1/status

Methods: GET

Gets status of the player.

Query parameters:

exclude: You can provide properties to exclude as list.

  • example value: exclude=playlist,track-list

Example response:

{
  "pause": true,
  "mute": false,
  "filename": "Dorohedoro 02 - In the Bag - Eat Quietly During Meals - My Neighbor the Sorcerer.mkv",
  "duration": 1422.061,
  "position": 71.787,
  "remaining": 1350.274,
  "media-title": "Dorohedoro 02 - In the Bag | Eat Quietly During Meals | My Neighbor the Sorcerer",
  "playlist": [
    {
      "index": 0,
      "id": 1,
      "filePath": "V:\\anime\\Vivy - Fluorite Eye's Song S01 1080p\\Vivy - Fluorite Eye's Song - E02.mkv",
      "filename": "Vivy - Fluorite Eye's Song - E02.mkv"
    },
    {
      "index": 1,
      "id": 2,
      "filePath": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)\\Dorohedoro 02 - In the Bag - Eat Quietly During Meals - My Neighbor the Sorcerer.mkv",
      "current": true,
      "filename": "Dorohedoro 02 - In the Bag - Eat Quietly During Meals - My Neighbor the Sorcerer.mkv"
    }
  ],
  "chapter": 0,
  "chapter-list": [
    {
      "title": "Intro",
      "time": 0
    },
    {
      "title": "OP",
      "time": 68.986
    },
    {
      "title": "Part A",
      "time": 159.034
    },
    {
      "title": "Part B",
      "time": 589.089
    },
    {
      "title": "ED",
      "time": 1316.023
    },
    {
      "title": "Preview",
      "time": 1406.03
    }
  ],
  "volume": 100,
  "max-volume": 100,
  "fullscreen": false,
  "speed": 1,
  "sub-delay": 0,
  "sub-visibility": true,
  "track-list": [
    {
      "index": 0,
      "id": 1,
      "type": "video",
      "selected": true,
      "codec": "hevc",
      "demux-w": 1920,
      "demux-h": 1080
    },
    {
      "index": 1,
      "id": 1,
      "type": "audio",
      "selected": true,
      "codec": "opus",
      "demux-channel-count": 2,
      "demux-channels": "unknown2",
      "demux-samplerate": 48000,
      "lang": "jpn"
    },
    {
      "index": 2,
      "id": 2,
      "type": "audio",
      "selected": false,
      "codec": "opus",
      "demux-channel-count": 2,
      "demux-channels": "unknown2",
      "demux-samplerate": 48000,
      "lang": "eng"
    },
    {
      "index": 3,
      "id": 1,
      "type": "sub",
      "selected": true,
      "codec": "subrip",
      "lang": "hun"
    },
    {
      "index": 4,
      "id": 2,
      "type": "sub",
      "selected": false,
      "codec": "ass",
      "lang": "eng"
    },
    {
      "index": 5,
      "id": 3,
      "type": "sub",
      "selected": false,
      "codec": "ass",
      "lang": "eng"
    }
  ],
  "audio-delay": 0,
  "sub-font-size": 55,
  "sub-ass-override": true,
  "metadata": {}
}

Media controls

/api/v1/controls/play-pause

Methods: POST

Cycles between play and pause

/api/v1/controls/play

Methods: POST

Start playback

/api/v1/controls/pause

Methods: POST

Pause playback

/api/v1/controls/stop

Methods: POST

Stops the playback, also clears playlist

/api/v1/controls/prev

Alias for /playlist/prev

/api/v1/controls/next

Alias for /playlist/next

/api/v1/controls/fullscreen

Methods: POST

Toggles fullscreen mode

/api/v1/controls/mute

Methods: POST

Mutes volume

/api/v1/controls/volume/:value

Methods: POST

Sets volume

/api/v1/controls/seek

Methods: POST

Seek

Request JSON:

{
  "target": 10.0,
  "flag": "absolute-percent" // if no flag provided defaults to relative
}

Flags

  • relative (Default)
  • absolute

Playlist

/api/v1/playlist

Methods: GET, POST

Related MPV documentation: https://mpv.io/manual/master/#command-interface-[%3Coptions%3E]

GET

Gets Playlist items.

Response JSON:

[
  {
    "index": 0,
    "id": 1,
    "filePath": "V:\\anime\\Vivy - Fluorite Eye's Song S01 1080p\\Vivy - Fluorite Eye's Song - E02.mkv",
    "current": true,
    "filename": "Vivy - Fluorite Eye's Song - E02.mkv"
  },
  {
    "index": 1,
    "id": 2,
    "filePath": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)\\Dorohedoro 02 - In the Bag - Eat Quietly During Meals - My Neighbor the Sorcerer.mkv",
    "filename": "Dorohedoro 02 - In the Bag - Eat Quietly During Meals - My Neighbor the Sorcerer.mkv"
  }
]

POST

Puts an item to playlist.

Request JSON:

{
    "filename": "V:\\anime\\Vivy - Fluorite Eye's Song S01 1080p\\Vivy - Fluorite Eye's Song - E02.mkv",
    "flag": "replace",
    "seekTo": 60.0, // seekTo works only if flag is replace. Format seconds
    "file-local-options": [
      "http-header-fields": "'MyHeader: 1234', 'MyHeader2: 5678'"
    ]
}

flag possible values:

  • replace
  • append
  • append-play (Default)

/api/v1/playlist/remove/:index

Methods: DELETE

Deletes a playlist item.

/api/v1/playlist/move?fromIndex=0&toIndex=1

Methods: POST

Related MPV documentation: https://mpv.io/manual/master/#command-interface-playlist-move

Query parameters:

  • fromIndex (REQUIRED): Moves this item.
  • toIndex (REQUIRED): To this index.

Moves a playlist item (fromIndex), to desired destination (toIndex).

/api/v1/playlist/play/:index

Methods: POST

Plays playlist item.

Note: index can be current too, whcih gonna reload the current entry.

/api/v1/playlist/prev

Methods: POST

Playlist previous item on playlist

/api/v1/playlist/next

Methods: POST

Playlist next item on playlist

/api/v1/playlist/clear

Methods: POST

Clears playlist.

/api/v1/playlist/shuffle

Methods: POST

Shuffle the playlist.

Tracks

/api/v1/tracks

Methods: GET

Gets all audio, video, subtitle tracks.

Example response:

[
  {
    "index": 0,
    "id": 1,
    "type": "video",
    "selected": true,
    "codec": "hevc",
    "demux-w": 1920,
    "demux-h": 1080
  },
  {
    "index": 1,
    "id": 1,
    "type": "audio",
    "selected": true,
    "codec": "opus",
    "demux-channel-count": 2,
    "demux-channels": "unknown2",
    "demux-samplerate": 48000,
    "lang": "jpn"
  },
  {
    "index": 2,
    "id": 2,
    "type": "audio",
    "selected": false,
    "codec": "opus",
    "demux-channel-count": 2,
    "demux-channels": "unknown2",
    "demux-samplerate": 48000,
    "lang": "eng"
  },
  {
    "index": 3,
    "id": 1,
    "type": "sub",
    "selected": true,
    "codec": "subrip",
    "lang": "hun"
  },
  {
    "index": 4,
    "id": 2,
    "type": "sub",
    "selected": false,
    "codec": "ass",
    "lang": "eng"
  },
  {
    "index": 5,
    "id": 3,
    "type": "sub",
    "selected": false,
    "codec": "ass",
    "lang": "eng"
  }
]

/api/v1/tracks/audio/reload/:id

Methods: POST

Loads desired audio track ID

/api/v1/tracks/audio/cycle

Methods: POST

Cycles through audio tracks

/api/v1/tracks/audio/add

Methods: POST

Adds an audio track

Request JSON:

{
  "filename": "/home/usr/myaudio.mp3",
  "flag": "select" // if no flag provided defaults to select
}

Flags

  • select
  • auto
  • cached

/api/v1/tracks/audio/timing/:seconds

Methods: POST

Sets audio delay to provided second, can be negative.

/api/v1/tracks/sub/reload/:id

Methods: POST

Loads desired subtitle track ID

/api/v1/tracks/sub/timing/:seconds

Methods: POST

Sets sub delay to provided value, can be negative number.

/api/v1/tracks/sub/ass-override/:value

Methods: POST

Changes default behaviour of rendering ASS/SSA subtitles. MPV mostly renders ASS/SSA subtitles correctly, but if you need it, use it.

MPV related documentation: https://mpv.io/manual/master/#options-sub-ass-override

BE VERY CAREFUL SOME VALUES CAN BREAK PLAYBACK CHECK DOCUMENTATION ABOVE

Possible values:

  • no
  • yes
  • force
  • scale
  • strip

/api/v1/tracks/sub/toggle-visibility

Methods: POST

Toggles subtitle visibility

/api/v1/tracks/sub/visibility/:value

Methods: POST Sets subtitle visibility

Values can be:

  • true
  • false

/api/v1/tracks/sub/add

Methods: POST

Add subtitle file.

Request JSON:

{
  "filename": "/home/usr/mysub.srt",
  "flag": "select" // if no flag provided defaults to select
}

Flags

  • select
  • auto
  • cached

Filebrowser

Basic filebrowser which only accepts paths which included at server configured variable mpvremote-filebrowserpaths

/api/v1/filebrowser/paths

Methods: GET

Returns content of mpvremote-filebrowserpaths option paths indexed.

Response JSON:

[
  {
    "index": 0,
    "path": "/home/usr/media1"
  },
  {
    "index": 1,
    "path": "/home/usr/media2"
  },
  {
    "index": 2,
    "path": "/home/usr/media3"
  }
]

/api/v1/filebrowser/browse

Methods: POST

Browse a path or collection.

Request JSON:

  "path": "/home/usr/media2"
  // Or
  "collection_id": 1

/api/v1/filebrowser/browse/:index

Methods: GET

Note: Only MPV supported fileformats will return. Supported file formats

Returns files with types:

{
  "content": [
    {
      "priority": 1,
      "type": "directory",
      "name": "Feliratok",
      "fullPath": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)\\Feliratok",
      "lastModified": "2021-05-03T19:10:16.008Z"
    },
    {
      "priority": 2,
      "type": "video",
      "name": "Dorohedoro 01 - Caiman.mkv",
      "fullPath": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)\\Dorohedoro 01 - Caiman.mkv",
      "lastModified": "2021-05-03T19:09:21.857Z",
      "mediaStatus": {
        // Media status appears only when localdb enabled!
        "id": 2,
        "directory": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)",
        "file_name": "Dorohedoro 01 - Caiman.mkv",
        "current_time": 1422.0545,
        "finished": 1
      }
    },
    {
      "priority": 2,
      "type": "video",
      "name": "Dorohedoro 02 - In the Bag - Eat Quietly During Meals - My Neighbor the Sorcerer.mkv",
      "fullPath": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)\\Dorohedoro 02 - In the Bag - Eat Quietly During Meals - My Neighbor the Sorcerer.mkv",
      "lastModified": "2021-05-03T19:04:05.410Z",
      "mediaStatus": {
        "id": 1,
        "directory": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)",
        "file_name": "Dorohedoro 02 - In the Bag - Eat Quietly During Meals - My Neighbor the Sorcerer.mkv",
        "current_time": 596.853,
        "finished": 0
      }
    },
    {
      "priority": 2,
      "type": "video",
      "name": "Dorohedoro 03 - Night of the Dead ~ Duel! ~ In Front of the Main Department Store.mkv",
      "fullPath": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)\\Dorohedoro 03 - Night of the Dead ~ Duel! ~ In Front of the Main Department Store.mkv",
      "lastModified": "2021-05-03T19:04:26.434Z"
    }
  ],
  "dirname": "Dorohedoro S01+OVA (BD 1080p)",
  "prevDir": "V:\\anime",
  "cwd": "V:\\anime\\Dorohedoro S01+OVA (BD 1080p)"
}

/api/v1/drives

Gets drives from server. Only if mpvremote-unsafefilebrowsing=1.

If unsafe filebrowsing is disabled returns an error.

Note for Linux users: snap, flatpak virtual drives will be excluded!

Response JSON:

// Windows Example
[
  {
    "path": "C"
  },
  {
    "path": "D:"
  }
]
// Unix systems
[
  {
    "path": "/"
  },
  {
    "path": "/home"
  }
]

Collections

Local collection handling. Collections only works if you have enabled mpvremote-uselocaldb Collections entries only can be opened if mpvremote-filebrowserpaths contains the required paths.

/api/v1/collections

Methods: GET, POST

GET

Get all collections

Response JSON:

Array of collection.

POST

Creates a collection

type variable/enum created for future use:

  • 1: Movies
  • 2: TVShows
  • 3: Music

Request JSON:

  "name": "Anime",
  "type": 1,
  "paths": [
    {
      "path": "/home/usr/media1"
    },
    {
      "path": "/home/usr/media2"
    }
  ]

/api/v1/collections/:id

Methods: GET, PATCH, DELETE

GET

Gets collection

Response JSON:

{
  "id": 1,
  "name": "Anime",
  "type": 1,
  "paths": [
    {
      "id": 1
      "path": "/home/usr/media1"
    },
    {
      "id": 2,
      "path": "/home/usr/media2"
    }
  ]
}

PATCH

Updates collection.

Request JSON:

{
  "name": "Anime ja nai",
  "type": 2,
  "paths": [
    {
      "path": "/home/usr/media3" // Adds new path
    },
    {
      "id": 2,
      "path": "/home/usr/media2_other" // Updates existing path
    }
  ]
}

DELETE

Deletes collection.

/api/v1/collections/entries/:id

Methods: DELETE

Deletes a collection entry.

/api/v1/collections/:collection_id/entries

Adds collection entry to collection.

Methods: POST

Request JSON:

{
  "collection_id": 1,
  "path": "/home/usr/media4"
}

Computer actions

/api/v1/computer/:action

Methods: POST

action can be:

  • shutdown
  • reboot
  • quit