MPV-Remote

Overview

This Flask-based web interfaz provides a comprehensive media control interface for MPV media player, allowing users to manage bookmarks, radio stations, and control media playback through a web interface.

Features

• Media Playback Control

  • Play media from URLs
  • Pause, resume, skip tracks
  • Control volume and mute
  • Stop playback and set repeat mode

• Bookmark Management

  • Create, edit, and delete bookmarks
  • Play bookmarked content
  • Add bookmarks to your playlist

• Radio Station Management

  • Add, edit, and delete radio stations
  • Play radio streams

• Playlist Management

  • View current playlist
  • Remove tracks
  • Play any track

• Upload Your Music

  • Upload media files to the server
  • Manage tracks in playlist

• Play Your Local Music

  • Browse your music library
  • Create bookmarks
  • Explore setlists and play albums

• Search Albums in YTMusic

  • Search the YTMusic catalog
  • View album details
  • Play and bookmark albums

Prerequisites

• Python 3.9+
• MPV Media Player

Recommended

• yt-dlp

Installation

Note: <ver> in the file names is the version number.

Option 1: Install from Wheel (Recommended)

Download the latest wheel from Releases or build it yourself:

# Install directly from wheel
pip install mpv_remote-<ver>-py3-none-any.whl

Option 2: Install from Source

# Clone the repository
git clone https://github.com/csq/mpv-remote.git
cd mpv-remote

# Build and install
pip install build
python -m build
pip install dist/mpv_remote-<ver>-py3-none-any.whl

Option 3: Development Install

git clone https://github.com/csq/mpv-remote.git
cd mpv-remote
pip install -e .

Note: Dependencies (Flask, ytmusicapi, etc.) are automatically installed with the wheel. No manual requirements.txt installation needed.

Configuration

MPV socket:

mpv --input-ipc-server=/tmp/mpv_socket --idle

• Ensure MPV is running with a Unix socket enabled (default name socket: mpv_socket)

Command-Line Options

The application supports the following command-line arguments to customize its behavior:

OPTION	TYPE	DEFAULT	DESCRIPTION
--ipc-path	string	/tmp/mpv_socket	Path to the mpv player socket for IPC communication.
--host	string	127.0.0.1	Host address to bind the server to. Use 0.0.0.0 to accept external connections.
--port	integer	5000	Port number for the server to listen on.
--auth	string	None	User authentication credentials in the format username:password. When set, enables authentication for API requests.
--allow-upload	boolean	False	Enable file upload functionality. Use this flag to allow users to upload media files to the server.
--ytm-search	boolean	False	Enable ytmusic search. Enables YTMusic search. Users can search the YTMusic catalog.
--music-dir	string	None	Local music directory path. Allows users to search and play their music library.

Running app

Default

mpv-remote

• The application will start on http://localhost:5000

Custom

mpv-remote --ipc-path /tmp/mpv_skt --host 0.0.0.0 --port 5050

• Example for used only in trusted network

Enable authentication and file uploads:

mpv-remote --auth admin:secretpassword --allow-upload

Project structure

mpv-remote/
│
├── mpv_remote/
│   ├── __init__.py
│   ├── __main__.py
│   ├── database.py
│   ├── static/
│   │   ├── css/
│   │   │   ├── components.css
│   │   │   ├── base.css
│   │   │   └── pages/
│   │   │       ├── index.css
│   │   │       ├── music.css
│   │   │       ├── login.css
│   │   │       ├── form-pages.css
│   │   │       ├── list-pages.css
│   │   │       ├── ytmusic.css
│   │   │       ├── bookmark/
│   │   │       │   ├── bookmark.css
│   │   │       │   └── bookmark_form.css
│   │   │       └── radio/
│   │   │           ├── radio.css
│   │   │           └── radio_form.css
│   │   └── fontawesome/
│   │       ├── css/
│   │       ├── js/
│   │       └── webfonts/
│   └── templates/
│       ├── base.html
│       ├── index.html
│       ├── login.html
│       ├── music.html
│       ├── ytmusic.html
│       ├── bookmark/
│       │   ├── bookmark.html
│       │   └── bookmark_form.html
│       └── radio/
│           ├── radio.html
│           └── radio_form.html
│
├── pyproject.toml
├── MANIFEST.in
├── LICENSE
├── README.md
└── preview.gif

Troubleshooting

• Ensure MPV is running with a socket enabled
• Check that the socket path is correct

Best Usage

For an optimal experience, combine mpv with yt-dlp.

Ideal Setup

A great way to utilize this combination is with an old smartphone running Termux as a jukebox.

mpv configuration

To set up mpv, use the following command:

mpv --input-ipc-server=/tmp/mpv_socket --no-video --ytdl-format=bestaudio --idle

mpv-remote configuration

For mpv-remote, run:

mpv-remote --host 0.0.0.0

Enjoy your enhanced media experience!