{"id":15441860,"url":"https://github.com/open-dynamix/simple-mpv-webui","last_synced_at":"2025-05-08T00:21:01.209Z","repository":{"id":31331366,"uuid":"116134471","full_name":"open-dynaMIX/simple-mpv-webui","owner":"open-dynaMIX","description":"A web based user interface with controls for the mpv mediaplayer.","archived":false,"fork":false,"pushed_at":"2024-01-31T11:43:32.000Z","size":3753,"stargazers_count":144,"open_issues_count":8,"forks_count":16,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-31T15:33:45.394Z","etag":null,"topics":["mpv","mpv-script","remote","remote-control","webui"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"makedin/mpv-web-ui","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-dynaMIX.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-03T12:28:40.000Z","updated_at":"2025-03-22T01:56:28.000Z","dependencies_parsed_at":"2024-10-31T15:02:50.195Z","dependency_job_id":"05e59979-851c-46d2-a5a0-f93a4cd7a2f1","html_url":"https://github.com/open-dynaMIX/simple-mpv-webui","commit_stats":{"total_commits":427,"total_committers":13,"mean_commits":32.84615384615385,"dds":0.5011709601873536,"last_synced_commit":"3c753450dd827d11eb6b6b8ff926e55af850478d"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-dynaMIX%2Fsimple-mpv-webui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-dynaMIX%2Fsimple-mpv-webui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-dynaMIX%2Fsimple-mpv-webui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-dynaMIX%2Fsimple-mpv-webui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-dynaMIX","download_url":"https://codeload.github.com/open-dynaMIX/simple-mpv-webui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252974346,"owners_count":21834244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mpv","mpv-script","remote","remote-control","webui"],"created_at":"2024-10-01T19:23:46.115Z","updated_at":"2025-05-08T00:21:01.148Z","avatar_url":"https://github.com/open-dynaMIX.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# simple-mpv-webui\n\n[![Build Status](https://github.com/open-dynaMIX/simple-mpv-webui/workflows/Tests/badge.svg)](https://github.com/open-dynaMIX/simple-mpv-webui/actions?query=workflow%3ATests)\n[![License](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/licenses/MIT)\n\nA web based user interface with controls for the [mpv mediaplayer](https://mpv.io/).\n\n * [Usage](#usage)\n + [Options](#options)\n - [port (int)](#port-int)\n - [ipv4 (bool)](#ipv4-bool)\n - [ipv6 (bool)](#ipv6-bool)\n - [disable (bool)](#disable-bool)\n - [logging (bool)](#logging-bool)\n - [osd_logging (bool)](#osd_logging-bool)\n - [audio_devices (string)](#audio_devices-string)\n - [static_dir](#static_dir)\n - [htpasswd_path](#htpasswd_path)\n - [collections](#collections)\n + [Setting options](#setting-options)\n - [CLI](#cli)\n - [mpv config file](#mpv-config-file)\n - [Webui config file](#webui-config-file)\n + [Authentication](#authentication)\n * [Dependencies](#dependencies)\n + [Linux](#linux)\n + [Windows](#windows)\n + [macOS](#macos)\n * [Screenshots](#screenshots)\n * [Key bindings](#key-bindings)\n * [Media Session API](#media-session-api)\n + [Playing other audio while using the webui on Android](#playing-other-audio-while-using-the-webui-on-android)\n * [Endpoints](#endpoints)\n + [List of endpoints](#list-of-endpoints)\n + [/api/status](#-api-status)\n * [Thanks](#thanks)\n * [Differences to mpv-web-ui](#differences-to-mpv-web-ui)\n * [Contributing](#contributing)\n\n## Usage\n\nFor mpv\u003e=v0.33.0 you can just clone/copy the whole repository into your mpv scripts\ndirectory.\n\nAlternatively you can also use the `--script` or `--scripts-append` option from mpv or\nadd something like `scripts-append=/path/to/simple-mpv-webui/` to `mpv.conf`.\n\n\u003cdetails\u003e\n \u003csummary\u003eInstalling for mpv \u0026lt;v0.33.0\u003c/summary\u003e\n\n Copy `webui.lua` and the `webui-page`-folder into your mpv scripts directory, mpv will\n then run it automatically.\n\n Alternatively you can also use the `--script` or `--scripts-append` option from mpv or\n add something like `scripts-append=/path/to/simple-mpv-webui/webui.lua` to `mpv.conf`.\n\n ---\n\u003c/details\u003e\n\nSee [dependencies](#dependencies) for more information about the installation.\n\nYou can access the webui when visiting [http://127.0.0.1:8080](http://127.0.0.1:8080) or\n[http://[::1]:8080](http://[::1]:8080) in your webbrowser.\n\nBy default, it listens on `0.0.0.0:8080` and `[::0]:8080`. As described below, this can be changed.\n\n### Options\n\nInformation about how to set options can be found [here](#setting-options).\n\n#### port (int)\nSet the port to serve the webui (default: 8080). Setting this allows for\nrunning multiple instances on different ports.\n\nExample:\n\n```\nwebui-port=8000\n```\n\n#### ipv4 (bool)\nEnable listening on ipv4 (default: yes)\n\nExample:\n\n```\nwebui-ipv4=no\n```\n\n#### ipv6 (bool)\nEnable listening on ipv6 (default: yes)\n\nExample:\n\n```\nwebui-ipv6=no\n```\n\n#### disable (bool)\nDisable webui (default: no)\n\nExample:\n\n```\nwebui-disable=yes\n```\n\n#### logging (bool)\nLog requests to STDOUT (default: no)\n\nExample:\n\n```\nwebui-logging=yes\n```\n\n#### osd_logging (bool)\nLog to OSD (default: yes)\n\nExample:\n\n```\nwebui-osd_logging=yes\n```\n\n#### audio_devices (string)\nSet the audio-devices used for cycling. By default it uses all interfaces MPV \nknows of.\n\nYou can see a list of them with following command:\n\n```shell\nmpv --audio-device=help\n```\n\nExample:\n\n```\nwebui-audio_devices=\"pulse/alsa_output.pci-0000_00_1b.0.analog-stereo pulse/alsa_output.pci-0000_00_03.0.hdmi-stereo\"\n```\n\n#### static_dir\n\nConfigure the directory from which the static files should be served.\n\nThis is useful, if you want to use an alternative frontend.\n\nThe provided path may be absolute or relative.\n\nExample:\n\n```\nwebui-static_dir=\"/path/to/directory\"\n```\n\nContent types are hardcoded into the server. If you miss something, please\n[create an issue](https://github.com/open-dynaMIX/simple-mpv-webui/issues/new/choose) or - even better -\na pull request.\n\n#### htpasswd_path\n\nSee [authentication](#authentication) below.\n\nExample:\n\n```\nwebui-htpasswd_path=\"/path/to/file\"\n```\n\nRelative paths are searched relative to the program's current working directory,\nso stick to absolute paths all the time.\n\nShortcuts to your homedir like `~/` are not supported.\n\n#### collections\n\nIn order to use the basic file-browser API at `/api/collections`, the absolute paths of\nto-be exposed directories need to be configured here (semicolon delimited). By default,\nresponses from `/api/collections` remain empty.\n\nExample:\n\n```\nwebui-collections=\"/home/user/Music;/home/user/Videos\"\n```\n\n### Setting options\n\nThere are three ways to set an option for the webui. Please refer to the MPV\ndocumentation for more details about this, as this is no feature of the webui.\n\n#### CLI\n\nIf you want to set webui-options from the CLI, you need to pass them to `--script-opts`\nor `--script-opts-add` respectively, like this: `--script-opts-add=webui-osd_logging=no`.\n\n#### mpv config file\n\nIf you want to set webui-options in the main mpv config file, you need to write it like\nthis: `script-opts-add=webui-osd_logging=no`.\n\n#### Webui config file\n\nFinally, if you want to webui-options in their dedicated config file, you can put them\nin a file `/path/to/mpv/user/dir/script-opts/webui.conf` (usually\n`~/.config/mpv/script-opts/webui.conf` on Linux) like this: `osd_logging=no`.\n\n\n### Authentication\nThere is a very simple implementation of\n[Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).\n\nIt can be enabled by providing the htpasswd file via the [htpasswd_path](#htpasswd_path) option.\nThe file does not need to be named `htpasswd`.\n\nThe provided file needs to contain data in the following format:\n\n```\nuser1:password1\nuser2:password2\n```\n\nOnly plaintext `.htpasswd` entries are supported.\n\n## Dependencies\n\n### Linux\n\n - [luasocket](https://github.com/diegonehab/luasocket)\n\n### Windows\n\nIn [this repository](https://github.com/57op/simple-mpv-webui-windows-libs) you can find a guide,\nbuild script and pre-built binaries.\n\nThanks to [@57op](https://github.com/57op) for providing this!\n\n### macOS\n\nInstall luarocks:\n\n```\nbrew install luarocks\n```\n\nCheck lua version of your mpv instance.\n\n```\nmpv -v\n\n...\n--lua=51deb # \u003c- this is your lua version\n...\n```\n\nProceed to install correct luasocket:\n\n```\nluarocks --lua-dir=/usr/local/opt/lua@5.1 install luasocket\n```\n\nSet correct path:\n\n```\neval $(luarocks --lua-dir=/usr/local/opt/lua@5.1 path --bin)\n```\n\n## Screenshots\n![webui screenshot](screenshots/webui.png#2)\n\n![playlist screenshot](screenshots/playlist.png#1)\n\n## Key bindings\nThere are some keybindings available:\n\n| Key | Function |\n| ---------- | ---------------------------- |\n| SPACE | Play/Pause |\n| ArrowRight | seek +10 |\n| ArrowLeft | seek -10 |\n| ArrowUp | seek +1min |\n| ArrowDown | seek -1min |\n| PageDown | seek +3 |\n| PageUp | seek -3 |\n| 9 | decrease volume |\n| 0 | increase volume |\n| f | toggle fullscreen |\n| n | playlist next |\n| p | playlist previous |\n| j | cycle subtitles |\n| v | toggle subtitle visibility |\n| [ | decrease playback speed |\n| ] | increase playback speed |\n| { | decrease playback speed more |\n| } | increase playback speed more |\n| Backspace | reset playback speed |\n| Escape | hide current overlay |\n| ? | toggle keyboard shortcuts |\n\n## Media Session API\nWhen using a browser that supports it, simple-mpv-webui uses the Media Session\nAPI to provide a notification with some metadata and controls:\n\n![notification screenshot](screenshots/notification.png#1)\n\nIn order to have the notification work properly you need to at least once trigger play from the webui.\n\n### Playing other audio while using the webui on Android\nFor the notification to work, the webui plays a silent audio file in a loop. This is\nnecessary in order for Chrome on Android to create such notification\n([see](https://developers.google.com/web/updates/2017/02/media-session#implementation_notes)).\nAs soon as this silent mp3 is played, audio from other apps is paused automatically by Android.\nThe only way to prevent this from happening is to disable the notifications, which is\npossible in the settings of the webui (client).\n\n## Endpoints\n\n### List of endpoints\n\n| URI | Method | Parameter | Description |\n| ---------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |\n| /api/status | GET | | Returns JSON data about playing media --\u003e see below |\n| /api/play | POST | | Play media |\n| /api/pause | POST | | Pause media |\n| /api/toggle_pause | POST | | Toggle play/pause |\n| /api/fullscreen | POST | | Toggle fullscreen |\n| /api/quit | POST | | Quit the program |\n| /api/add/:name/:value | POST | `string` and `int` or `float` | Add `:value` (default of `1`) to the `:name` property |\n| /api/cycle/:name/:value | POST | `string` and `up` or `down` | Cycle `:name` by `:value` (default of `up`) |\n| /api/multiply/:name/:value | POST | `string` and `int` or `float` | Multiply `:name` by `:value` |\n| /api/set/:name/:value | POST | `string` and anything | Set `:name` to `:value` |\n| /api/toggle/:name | POST | `string` | Toggle the boolean property |\n| /api/seek/:seconds | POST | `int` or `float` (can be negative) | Seek |\n| /api/set_position/:seconds | POST | | Go to position :seconds |\n| /api/playlist_prev | POST | | Go to previous media in playlist |\n| /api/playlist_next | POST | | Go to next media in playlist |\n| /api/playlist_jump/:index | POST | `int` | Jump to playlist item at position `:index` |\n| /api/playlist_move/:source/:target | POST | `int` and `int` | Move playlist item from position `:source` to position `:target` |\n| /api/playlist_move_up/:index | POST | `int` | Move playlist item at position `:index` one position up |\n| /api/playlist_remove/:index | POST | `int` | Remove playlist item at position `:index` |\n| /api/playlist_shuffle | POST | | Shuffle the playlist |\n| /api/loop_file/:mode | POST | `string` or `int` | Loop the current file. `:mode` accepts the same loop modes as mpv |\n| /api/loop_playlist/:mode | POST | `string` or `int` | Loop the whole playlist `:mode` accepts the same loop modes as mpv |\n| /api/add_chapter/:amount | POST | `int` (can be negative) | Jump `:amount` chapters in current media |\n| /api/add_volume/:percent | POST | `int` or `float` (can be negative) | Add :percent% volume |\n| /api/set_volume/:percent | POST | `int` or `float` | Set volume to :percent% |\n| /api/add_sub_delay/:ms | POST | `int` or `float` (can be negative) | Add :seconds seconds subtitles delay |\n| /api/set_sub_delay/:ms | POST | `int` or `float` (can be negative) | Set subtitles delay to :ms milliseconds |\n| /api/add_audio_delay/:seconds | POST | `int` or `float` (can be negative) | Add :seconds seconds audio delay |\n| /api/set_audio_delay/:seconds | POST | `int` or `float` (can be negative) | Set audio delay to :seconds milliseconds |\n| /api/cycle_sub | POST | | Cycle trough available subtitles |\n| /api/cycle_audio | POST | | Cycle trough available audio tracks |\n| /api/cycle_audio_device | POST | | Cycle trough audio devices. [More information.](#audio-devices-string) |\n| /api/speed_set/:speed | POST | `int` or `float` | Set playback speed to `:speed` (defaults to `1` for quick reset) |\n| /api/speed_adjust/:amount | POST | `int` or `float` | Multiply playback speed by `:amount` (where `1.0` is no change) |\n| /api/loadfile/:path/:mode | POST | :path URL encoded `string` \u003cbr /\u003e:mode `string` options: `replace` (default), `append`, `append-play` | Load file to playlist. Together with youtube-dl, this also works for URLs |\n| /api/collections/:path | GET | If no :path is provided, the configured collections are returned. | List directories and files (see [collections](#collections)) |\n\n\nAll POST endpoints return a JSON message. If successful: `{\"message\": \"success\"}`, otherwise, the message will contain\ninformation about the error.\n\n### /api/status\n`metadata` contains all the metadata mpv can see, below is just an example:\n\n``` json\n{\n \"audio-delay\": 0, # \u003c-- milliseconds\n \"audio-devices\": [\n {\"active\": true, \"description\": \"Autoselect device\", \"name\": \"auto\"},\n {\"active\": false, \"description\": \"Default (alsa)\", \"name\": \"alsa\"},\n {\"active\": false, \"description\": \"Default (jack)\", \"name\": \"jack\"},\n {\"active\": false, \"description\": \"Default (sdl)\", \"name\": \"sdl\"},\n {\"active\": false, \"description\": \"Default (sndio)\", \"name\": \"sndio\"},\n ],\n \"chapter\": 0, # \u003c-- current chapter\n \"chapters\": 0, # \u003c-- chapters count\n \"chapter-list\": [ # Array length == \"chapters\".\n {\n \"title\": \"Chapter 0\",\n \"time\": 0, # \u003c-- start time in seconds\n },\n ],\n \"duration\": 6.024, # \u003c-- seconds\n \"end\": null, # \u003c-- seconds as string or null\n \"filename\": \"01 - dummy.mp3\",\n \"fullscreen\": false,\n \"loop-file\": false, # \u003c-- false, true or integer\n \"loop-playlist\": false, # \u003c-- false, `inf`, `force` or integer\n \"metadata\": { # \u003c-- all metadata available to MPV\n \"album\": \"Dummy Album\",\n \"artist\": \"Dummy Artist\",\n \"comment\": \"0\",\n \"date\": \"2020\",\n \"encoder\": \"Lavc57.10\",\n \"genre\": \"Jazz\",\n \"title\": \"First dummy\",\n },\n \"pause\": true,\n \"playlist\": [\n {\n \"current\": true,\n \"filename\": \"./environment/test_media/01 - dummy.mp3\",\n \"id\": 1,\n \"playing\": true,\n },\n {\"filename\": \"./environment/test_media/02 - dummy.mp3\", \"id\": 2},\n {\"filename\": \"./environment/test_media/03 - dummy.mp3\", \"id\": 3},\n ],\n \"position\": -0.0, # \u003c-- seconds\n \"remaining\": 6.024, # \u003c-- seconds\n \"speed\": 1, # \u003c-- multiplier\n \"start\": null, # \u003c-- seconds as string or null\n \"sub-delay\": 0, # \u003c-- milliseconds\n \"track-list\": [ # \u003c-- all available video, audio and sub tracks\n {\n \"albumart\": false,\n \"audio-channels\": 2,\n \"codec\": \"mp3\",\n \"decoder-desc\": \"mp3float (MP3 (MPEG audio layer 3))\",\n \"default\": false,\n \"demux-channel-count\": 2,\n \"demux-channels\": \"stereo\",\n \"demux-samplerate\": 48000,\n \"dependent\": false,\n \"external\": false,\n \"ff-index\": 0,\n \"forced\": false,\n \"id\": 1,\n \"image\": false,\n \"main-selection\": 0,\n \"selected\": true,\n \"src-id\": 0,\n \"type\": \"audio\",\n }\n ],\n \"volume\": 0,\n \"volume-max\": 130,\n}\n```\n\n## Thanks\nThanks to [makedin](https://github.com/makedin) for his work on this.\n\n## Differences to mpv-web-ui\n - More media controls\n - Playlist controls\n - Some styles and font-awesome\n - ipv6 support\n - Option to set the port being used (defaults to 8080)\n - Using the Media Session API\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-dynamix%2Fsimple-mpv-webui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-dynamix%2Fsimple-mpv-webui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-dynamix%2Fsimple-mpv-webui/lists"}