https://github.com/jmatth11/player.nvim
A simple plugin to play local audio/music through neovim
https://github.com/jmatth11/player.nvim
audio music nvim player zig
Last synced: 7 months ago
JSON representation
A simple plugin to play local audio/music through neovim
- Host: GitHub
- URL: https://github.com/jmatth11/player.nvim
- Owner: jmatth11
- License: mit
- Created: 2025-10-08T23:53:10.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-11-14T23:07:40.000Z (7 months ago)
- Last Synced: 2025-11-15T00:17:40.913Z (7 months ago)
- Topics: audio, music, nvim, player, zig
- Language: C
- Homepage:
- Size: 1.22 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Player.nvim
Simple plugin to play local audio files through neovim. (currently only tested on linux-like environments)
## Contents
- [Dependencies](#dependencies)
- [Build Dependencies](#build-dependencies)
- [Building](#building)
- [Configure](#configure)
- [Usage](#usage)
- [Recommended Mappings](#recommended-mappings)
- [Manual Controls](#manual-controls)
- [Screenshots](#screenshots)
- [Demo](#demo)
- [Known Issues](#known-issues)
## Dependencies
- [`nvim-lua/plenary.nvim`](https://github.com/nvim-lua/plenary.nvim) - for window management.
### Build Dependencies:
This project requires either option A or option B dependencies to be installed
on the user's system to build the project.
Option A:
- [Zig](https://github.com/ziglang/zig) v0.15.2
Option B:
- [Curl](https://github.com/curl/curl)
- [Tar](https://www.gnu.org/software/tar/)
## Building
This project uses [Zig](https://github.com/ziglang/zig) but you don't need to
have Zig installed to build.
Use the `build.sh` script to build the project.
This script will check if Zig already exists on the system. If Zig does not exist
or if the system Zig is the wrong version, the script will download the correct
Zig executable temporarily to build. Once the build is complete, the
temporary Zig executable will be removed.
## Configure
Lazy.nvim
```lua
'jmatth11/player.nvim',
-- build script may take a some time if you don't already have zig on your system
build = "./build.sh",
-- Required to properly setup the player.
config = true,
dependencies = {
"nvim-lua/plenary.nvim", -- required for window management
},
```
Setup options:
```lua
{
-- Set the parent directory for your audio files.
-- default is home directory
parent_dir = vim.env.HOME,
-- The scale at which the volume increments and decrements.
-- default is 5
volume_scale = 5,
-- Flag to redraw the player info window every second when it's open.
-- Default is true.
live_update = true,
-- Search for songs in the parent directory recursively.
-- Default is false.
recursive = false,
}
```
## Usage
The plugin is configured to kill the player automatically when you exit neovim.
So there is no need to call it yourself.
### Recommended Mappings
```lua
-- pp to toggle the player info window.
vim.keymap.set(
"n",
"pp",
":lua require('player').player_info()",
{noremap = true},
)
-- pf to toggle the file select window.
vim.keymap.set(
"n",
"pf",
":lua require('player').file_select()",
{noremap = true},
)
```
Using the player info window or the file select window is the recommended way
to interact with this plugin. These windows display their respective
key-bindings to perform tasks.
The player info window allows you to control the pause/resume/stop action of
the song as well as increasing or lowering the volume.
The file select window displays all the songs from your parent directory and allows
you press `` to start playing a song from the list.
### Manual Controls
Play a song.
This function will prepend the parent directory set in the setup options.
So you only need to pass the filename relative to that point.
```lua
require('player').play()
```
Controlling pause/resume.
```lua
require('player').pause()
require('player').resume()
```
Controlling volume.
```lua
require('player').volume_up()
require('player').volume_down()
```
Open control windows.
```lua
-- The player info on the currently playing song.
require('player').player_info()
-- The file selection window of the music within your parent directory.
require('player').file_select()
```
## Screenshots
## Demo
https://github.com/user-attachments/assets/5a35b49d-d420-4d13-be69-13637d7cc59b
## Known issues
- Audio playback on WSL is not great and sometimes becomes very choppy.
[ref](https://github.com/microsoft/wslg/issues/908)