open_in_mpv

README

open-in-mpv

---

This is a simple web extension (for Chrome and Firefox) which helps open any video in the currently open tab in the mpv player.

The extension itself shares a lot of code with the one from the awesome iina, while the (bare) backend is written in Go (this is a rewrite from C++).

• Installation
• Configuration
  • Flag overrides
  • Example
• The mpv:// protocol
• Playlist and enqueue functionality
• Player support

Installation

Compiled binaries and packed extensions can be found in the releases page.

To build and install open-in-mpv and the mpv:// protocol handler, just run

$ sudo make install
$ make install-protocol

Configuration

The configuration file has to be named config.yml and can be placed in the same folder as the executable or in:

• Windows: C:\Users\<user>\AppData\Roaming\open-in-mpv\
• Linux: ~/.config/open-in-mpv/
• Mac: ~/Library/Application Support/open-in-mpv/

The configuration file has the following structure:

fake: [ open_in_mpv.Player ]
  name: [ string ]
  executable: [ string ]
  fullscreen: [ string ]
  pip: [ string ]
  enqueue: [ string ]
  new_window: [ string ]
  needs_ipc: [ true | false ]
  flag_overrides: [ map[string]string ]

See the default configuration as an example

And the open_in_mpv.Player object is defined as follows:

Key	Example value	Description
name	mpv	Full name of the video player; not used internally
executable	mpv	The player's binary path/name (doesn't need full path if already in $PATH)
fullscreen	"--fs"	Flag override to open the player in fullscreen (can be empty)
pip	"--pip"	Flag override to open the player in picture-in-picture mode (can be empty)
enqueue	"--enqueue"	Flag override to add the video to the player's queue (can be empty)
new_window	"--new-window"	Flag override to force open a new player window with the video (can be empty)
needs_ipc	false	Controls whether the player needs IPC communication (only generates mpv-compatible JSON commands, used for enqueing videos)
flag_overrides	"*": "--mpv-options=%s"	Defines arbitrary text overrides for command line flags (see below)

Flag overrides

The configuration for a player can contain overrides for command line flags defined in the web extension's configuration page, so not to make a different player crash/not start because the flags are not accepted. With the correct overrides any kind of flag passed in the URL by the extension will either be ignored or replaced with a pattern/prefix/suffix so that it becomes valid for the player in use.

• "*": matches anything and will take precedence over any other override
  • e.g. the pair "*": "" will void all flags
• "flag": matches the flag --flag
  • e.g. the pair "--foo": "--bar" will replace --foo with --bar
• "%s": is replaced with the original flag without any leading dash
  • e.g. the pair "--foo": "--%s-bar" will replace --foo with --foo-bar

Note: command line options with parameters such as --foo=bar are considered as a whole, single flag

Celluloid, for example, expects all mpv-related command line flags to be prefixed with --mpv-, so its configuration will contain the following overrides:

flag_overrides: 
  "*": "--mpv-%s"

Example

This is a full example of a fictitious player definition in the configuration file:

players:
  fake:
    name: fake-player
    executable: fakeplayer
    fullscreen: "--fs"
    pip: "--ontop --no-border --autofit=384x216 --geometry=98\\%:98\\%"
    enqueue: "--enqueue"
    new_window: ""
    needs_ipc: true
    flag_overrides:
      "*": "--mpv-options=%s"

The mpv:// protocol

open-in-mpv install-protocol will create a custom xdg-open desktop file with a scheme handler for the mpv:// protocol. This lets xdg-open call open-in-mpv with an encoded URI, so that it can be parsed and the information can be relayed to mpv - this logic follows how iina parses and opens custom URIs with the iina:// protocol on Mac. install-protocol.sh has the same functionality.

Please note that this specification is enforced quite strictly, as the program will error out when:

• The protocol is not mpv://
• The method/path is not /open
• The query is empty

The table below is a simple documentation of the URL query keys and values used to let the open-in-mpv executable what to do.

Key	Example value	Description
url	https%3A%2F%2Fyoutu.be%2FdQw4w9WgXcQ	The actual file URL to be played, URL-encoded
full_screen	1	Controls whether the video is played in fullscreen mode
pip	1	Simulates a picture-in-picture mode (only works with mpv for now)
enqueue	1	Adds a video to the queue (see below)
new_window	1	Forcibly starts a video in a new window even if one is already open
player	celluloid	Starts any supported video player (see Player support)
flags	--vo%3Dgpu	Custom command options and flags to be passed to the video player, URL-encoded

Playlist and enqueue functionality

For enqueue to work properly with any mpv-based player (provided it supports mpv's IPC), the player has to read commands from a socket. This can be achieved by adding the following line to the video player's configuration (usually $HOME/.config/mpv/mpv.conf for mpv).

input-ipc-server=/tmp/mpvsocket

Player support

Supported players are defined in config.yml, where the struct Player (see config.go) defines supported functionality and command line flag overrides. To request support for a player you're welcome to open a new issue or a pull request or just add your own in your configuration file.

Documentation

Index

• func LoadConfig() error
• func SendBytes(cmd []byte) error
• func SendString(cmd string) error
• type Config
• type Ipc
  • func (i *Ipc) Send(cmd []byte) error
• type Options
  • func NewOptions() Options
  • func (o Options) GenerateCommand() []string
  • func (o Options) GenerateIPC() ([]byte, error)
  • func (o *Options) Parse(uri string) error
• type Player
  • func GetPlayerInfo(name string) *Player

Functions

func LoadConfig

func LoadConfig() error

Tries to load configuration file with fallback

func SendBytes

func SendBytes(cmd []byte) error

Generic public send byte-encoded string command for the default connection

func SendString

func SendString(cmd string) error

Generic public send string command for the default connection

Types

type Config

type Config struct {
	Players map[string]Player
}

Top-level configuration object, maps a player by name to its Player object

type Ipc

type Ipc struct {
	SocketAddress string
	// contains filtered or unexported fields
}

Defines an IPC connection with a UNIX socket

func (*Ipc) Send

func (i *Ipc) Send(cmd []byte) error

Send a byte-encoded command to the specified UNIX socket

type Options

type Options struct {
	Flags      string
	Player     string
	Url        string
	Enqueue    bool
	Fullscreen bool
	NewWindow  bool
	Pip        bool
	NeedsIpc   bool
}

The Options struct defines a model for the data contained in the mpv:// URL and acts as a command generator (both CLI and IPC) to spawn and communicate with an mpv player window.

func NewOptions

func NewOptions() Options

Default constructor for an Option object

func (Options) GenerateCommand

func (o Options) GenerateCommand() []string

Builds a CLI command used to invoke the player with the appropriate arguments

func (Options) GenerateIPC

func (o Options) GenerateIPC() ([]byte, error)

Builds the IPC command needed to enqueue videos if the player requires it

func (*Options) Parse

func (o *Options) Parse(uri string) error

Parse a mpv:// URL and populate the current Options

type Player

type Player struct {
	// Full name of the player
	Name string
	// Executable path/name (if already in $PATH) for the player
	Executable string
	// Flag override for fullscreen
	Fullscreen string
	// Flag override for picture-in-picture mode
	Pip string
	// Flag override for enqueuing videos
	Enqueue string
	// Flag override for forcing new window
	NewWindow string `yaml:"new_window"`
	// Controls whether this player needs IPC command to enqueue videos
	NeedsIpc bool `yaml:"needs_ipc"`
	// Overrides for any generic flag
	FlagOverrides map[string]string `yaml:"flag_overrides"`
}

The Player struct contains useful informations for an mpv-based player, such as binary name and fullscreen/pip/enqueue/new_window flags overrides for use in GenerateIPC(). A way to override any generic flags is also provided through the map FlagOverrides.

func GetPlayerInfo

func GetPlayerInfo(name string) *Player

Returns player information for the given name if present, otherwise nil