{"id":13753889,"url":"https://github.com/gmt4/mpvc","last_synced_at":"2025-05-09T21:36:02.899Z","repository":{"id":63403187,"uuid":"480754281","full_name":"gmt4/mpvc","owner":"gmt4","description":"An mpc-like interface to control mpv from the terminal + extra goodies 🚀","archived":false,"fork":true,"pushed_at":"2024-04-13T17:04:44.000Z","size":3144,"stargazers_count":77,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-14T07:51:43.984Z","etag":null,"topics":["bsd","cli","fzf","invidious","macos","media-player","mpv","mpv-scripts","mpvc","mpvc-tui","mpvc-web","mpvctl","posix-sh","terminal","tui"],"latest_commit_sha":null,"homepage":"https://gmt4.github.io/mpvc/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"lwilletts/mpvc","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gmt4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-04-12T10:09:50.000Z","updated_at":"2024-04-03T13:25:13.000Z","dependencies_parsed_at":"2023-02-12T08:16:20.851Z","dependency_job_id":"dd2e26f4-2b54-46ff-93ae-d48186e318d1","html_url":"https://github.com/gmt4/mpvc","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmt4%2Fmpvc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmt4%2Fmpvc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmt4%2Fmpvc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmt4%2Fmpvc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gmt4","download_url":"https://codeload.github.com/gmt4/mpvc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253329046,"owners_count":21891568,"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":["bsd","cli","fzf","invidious","macos","media-player","mpv","mpv-scripts","mpvc","mpvc-tui","mpvc-web","mpvctl","posix-sh","terminal","tui"],"created_at":"2024-08-03T09:01:32.890Z","updated_at":"2025-05-09T21:36:02.891Z","avatar_url":"https://github.com/gmt4.png","language":"Shell","readme":"# 🎧 mpvc\n\n![GitHub](https://img.shields.io/github/license/lwilletts/mpvc)\n![GitHub Release Date](https://img.shields.io/github/release-date/lwilletts/mpvc)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/lwilletts/mpvc)\n![GitHub top language](https://img.shields.io/github/languages/top/lwilletts/mpvc)\n![GitHub lines of Code](https://sloc.xyz/github/lwilletts/mpvc/?category=code)\n\nMusic player in POSIX-sh interfacing mpv from the shell + extras/goodies [^install] 🚀.\n\nA fork of [lwillets/mpvc](https://github.com/lwilletts/mpvc) evolving on its own adding features such as: improved interfaces to CLI, TUI, FZF, WEB, EQZ, \u0026 play streaming services as YouTube/Invidious.\nFor more on the features of this fork check: [Git](#git) QuickStart, [Wiki](../../wiki), [LogBook](../../wiki#logbook) \u0026 [Casts](../../wiki#screencasts).\n\n⏩ Skip directly to [Installation](#Installation) to try mpvc!\n\n\u003cdetails open\u003e\n\u003csummary\u003empvc-tui -T: running the mpvc TUI \u003ci\u003e(click to view screenshot)\u003c/i\u003e\u003c/summary\u003e\n\n![mpvc-tui -T screenshot](../../blob/master/docs/assets/mpvc-tui.png)\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003empvc-fzf -f: running with fzf to manage the playlist \u003ci\u003e(click to view screenshot)\u003c/i\u003e\u003c/summary\u003e\n\n![mpvc-fzf screenshot](../../blob/master/docs/assets/mpvc-tui-arch.png)\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003empvc-tui -n: running with mpvc-fzf and desktop notifications on the upper-right corner \u003ci\u003e(click to view screenshot)\u003c/i\u003e\u003c/summary\u003e\n\n![mpvc tui+fzf+notifications screenshot](../../blob/master/docs/assets/mpvc-tui-fzf.png)\n\u003c/details\u003e\n\n## ▶️ Overview [^install]\n\n[mpvc](../../) is a collection of POSIX shell scripts:\n\n- [mpvc](../../blob/master/mpvc): provides the core CLI commands to control mpv\n- [extras/mpvc-tui](../../blob/master/extras/mpvc-tui): provides a console TUI, using mpvc underneath\n- [extras/mpvc-fzf](../../blob/master/extras/mpvc-fzf): provides FZF integration to mpvc.\n- [extras/mpvc-web](../../blob/master/extras/mpvc-web): a hack to remotely control mpvc from web (handy on mobile)\n- [extras/mpvc-mpris](../../blob/master/extras/mpvc-mpris): speaks MPRIS to control mpv player through key-bindings.\n- [extras/mpvc-equalizer](../../blob/master/extras/mpvc-equalizer): provides a basic mpv equalizer for the CLI.\n- [extras/mpvc-autostart](../../blob/master/extras/mpvc-autostart): automatic mpv start/stop based on presence.\n- [extras/mpvc-installer](../../blob/master/extras/mpvc-installer): provides an installer to install/update mpvc.\n\nFor more details on how to use the above tools have a look at the [Git](#git) QuickStart Guide, [LogBook](../../wiki#logbook).\nIn addition, the [casts/](../../wiki#screencasts) directory to shows some screencasts of mpvc in action.\n\n## Requirements\n\nRequired:\n- `sh`: a POSIX compliant shell (`/bin/sh` works)\n- `mpv`: the mpv media player (see https://mpv.io)\n- `socat`: is preferred due to the differing implementations of `netcat` across UNIXes.\n- `awk`: a sane version of `awk` for the same reason (GNU/BSD `awk` works)\n\nRecommended extras:\n\n- `curl`\n- `fzf`\n- `jq`\n- `notify-send`\n- `yt-dlp`\n\n## Installation\n\n- [Manual](#manual)\n- [Git](#git)\n- [Debian](#debian)\n- [Arch](#arch-mpvc-git)\n- [BSD](#bsd)\n- [MacOS](#macos)\n- [Gentoo](#gentoo-mpvc)\n- [Nix](#nix-mpvc)\n\nInstalling is just a matter of fetching the scripts either via [Git](#git)/Curl/etc., scripts can be used directly from the repo, the `mpvc-installer` bit is just there for easiness, to fetch \u0026 link them into your `BINDIR=~/bin/` that [mpvc-installer](../../blob/master/extras/mpvc-installer) does by default.\n\nThe easiest for a onetime install is the [Manual](#manual), however for @latest version a [Git](#git) install is recommended.\nRemember to check your installation for missing dependencies/requirements using `mpvc-installer check-reqs`, and, if you encounter any issue file an [Issue](../../issues).\n\n### Manual\n\n```console\ncurl -LO https://github.com/lwilletts/mpvc/raw/master/extras/mpvc-installer \\\n  \u0026\u0026 BINDIR=$HOME/bin sh ./mpvc-installer fetch-user\n```\n\n### Git\n\nBelow is a **Quick Start** guide showcasing mpvc git install and usage.\nThis does git clone, and symlinks the mpvc scripts to `BINDIR` (default `~/bin`), so updating becomes a matter of just running `git pull`.\n\n```sh\n # fetch a local copy of the github repo\n git clone https://github.com/lwilletts/mpvc/\n # use extras/mpvc-installer: just copy/link to BINDIR=$HOME/bin (by default)\n (cd mpvc; extras/mpvc-installer link-user)\n (cd mpvc; extras/mpvc-installer check-reqs)\n\n # use mpvc to add/load/save media files or online YT URLs\n mpvc add /path/to/your/*.mp3 # or your URLs\n find . -type f -name | mpvc load\n mpvc save my-playlist\n\n # use mpvc stash to store/recover current mpv state (see the logbook for more)\n mpvc stash ls\n mpvc stash push current\n mpvc stash apply current\n\n # use mpvc-fzf to manage mpvc stash (see mpvc-fzf -h for more)\n mpvc-fzf -a\n # use mpvc-fzf to search and play youtube media\n mpvc-fzf -p 'kupla mirage'\n # use mpvc-fzf to browse \u0026 play lofi girl music\n mpvc-fzf -b https://lofigirl.com/wp-content/uploads/2023/06\n # use mpvc-fzf to manage the playlist\n mpvc-fzf -f\n # use mpvc-tui to start the tui + desktop notifications\n mpvc-tui -T\n```\n\nFor more  check the  [LogBook](../../wiki#logbook) (remeber your best chance is to try, play, and have fun).\n\n### Debian\n\nDebian (and APT derivatives such as Ubuntu):\n\n```console\napt install mpv gawk curl socat fzf rlwrap jq libnotify-bin\n```\n\n### Arch [mpvc-git](https://aur.archlinux.org/packages/mpvc-git)\n\nArch (and derivatives):\n\n```console\npacaur -y mpvc-git\npacman -Sy mpv gawk curl socat fzf rlwrap jq libnotify\n````\n\n### BSD\n\nBSD (and pkg(1) based derivatives as FreeBSD, see [FAQ](../../wiki/FAQ)):\n\n```console\npkg install -y mpv curl socat fzf rlwrap jq libnotify # mpv-mpris\n```\n\n### MacOS\n\nMacOS (and brew(1) based derivatives see [FAQ](../../wiki/FAQ)):\n\n```console\nbrew install mpv curl socat fzf rlwrap jq libnotify yt-dlp\n```\n\n### Gentoo [mpvc](https://gitlab.com/xy2_/osman)\n\n```console\nemerge mpvc\n```\n\n### Nix [mpvc](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/mp/mpvc/)\n\n```console\nnix-env -i mpvc\n```\n\n## Usage\n\n### mpvc\n\n```console\nusage: mpvc opts # @version v1.7 (c) gmt4 https://github.com/gmt4/mpvc\n -a | --add | add         : Add media to playlist (see --load for stdin).\n -r | --remove | rm       : Remove media by id from playlist (see searchrm for rm by title)\n -s | --stop | stop       : Always stop playback.\n -P | --play | play       : Always start playback.\n -p | --toggle            : Toggle playback.\n    | --next              : Jump to next entry in the playlist\n    | --prev              : Jump to previous entry in the playlist\n -i | --playlist          : Print filenames of tracks to fit within terminal.\n -I | --fullplaylist      : Print all filenames of tracks in current playlist.\n -v | --vol               : Increase/decrease volume relative to current volume.\n -h | --help              : Prints the short help.\n -H | --help-long         : Prints the long help.\n*tips: If unsure about where to begin, have a look at https://gmt4.github.io/mpvc\n```\n\n### mpvc-tui\n\n```console\nusage: mpvc-tui opts # @version v1.7 (c) gmt4 https://github.com/gmt4/mpvc\n -d|dir     : Set the WD to the media directory given as argument\n -n|notify  : Desktop notification using notify on mpvc events (notify-send*)\n -s|suggest : Suggest a random media to play based on previous media played\n -S|scrobler: Starts the mpvc-tui scrobbler\n -H|history : Starts the mpvc-tui history\n -t|tui     : Starts the mpvc-tui to manage the mpv playlist (rlwrap*)\n -T|Tui     : Combo that starts mpvc-tui -t -n, and adds media given as args\n -x|launch  : Starts mpvc-tui in a new xterm ($MPVC_TUI_TERM) # combine with \u003copts\u003e\n -v|version : Prints the mpvc-tui version.\n*tips: If unsure about where to begin, start with: mpvc-tui -d /path/to/media/ -T\n````\n\n### mpvc-fzf\n\n```console\nusage: mpvc-fzf opts # @version v1.7 (c) gmt4 https://github.com/gmt4/mpvc\n -a|stash    : Start fzf to manage mpvc stashes\n -b|browse   : Start fzf to manage the provided ytdl-archive URL\n -c|chapters : Start fzf to manage the current mpv chapterlist\n -d|dir      : Set the WD to the media directory given as argument\n -e|eqz      : Start fzf to manage the equalizer settings\n -f|playlist : Start fzf to manage the current mpv playist\n -g|fetch    : Fetch the given YT URL, and store locally\n -G|Fetch    : Search on Invidious, fetch, and store locally\n -i|lyrics   : Search given media lyrics on Invidious\n -k|dplay    : Search \u0026 play DuckDuckGo videos\n -K|dsearch  : Search DuckDuckGo videos\n -l|local    : Search \u0026 play local media\n -s|search   : Search on Invidious\n -t|thumbnail: Retrieve thumbnail_url from metadata of the current YT-URL\n -T|Thumbnail: Retrieve thumbnail_url from metadata of the provided YT-URL\n -p|splay    : Search \u0026 play media found using Invidious\n -u|url      : Search the given YT URL (supports vids,channels,playlist feeds)\n -U|Url      : Search \u0026 play the given YT URL\n -x|launch   : Starts mpvc-fzf in a new xterm (config $MPVC_TERM) [combine -x with other opts]\n -y|related  : Search related media on Invidious\n -Y|Related  : Search \u0026 play related media using Invidious\n -z|relatedo : Search current media-title on Invidious and return related media\n -v|version  : Return the mpvc-fzf version.\n\n    now      : Return a shareable URL to the \"now listening\" playlist\n    lofi     : Search \u0026 play Lo-Fi channels\n    somafm   : Search \u0026 play SomaFM channels\n    radioapi : Search \u0026 play Radio-Browser API channels\n    ntsradio : Search \u0026 play NTS-Radio API channels\n    custom   : Search \u0026 play your custom feeds (channels, playlists, ...)\n*tips: If unsure about where to begin, start: mpvc-fzf -p 'kupla mirage'\n```\n\n[^install]: Skip directly to [Installation](#Installation) to try mpvc\n\n","funding_links":[],"categories":["Entertainment","Menu","Shell","\u003ca name=\"music\"\u003e\u003c/a\u003eSound and music","Table of Contents"],"sub_categories":["Music"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmt4%2Fmpvc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgmt4%2Fmpvc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmt4%2Fmpvc/lists"}