Player.nvim

Simple plugin to play local audio files through neovim. (currently only tested on linux-like environments)

Contents

• Dependencies
  • Build Dependencies
• Building
• Configure
• Usage
  • Recommended Mappings
  • Manual Controls
• Screenshots
• Demo
• Known Issues

Dependencies

• 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 v0.15.2

Option B:

• Curl
• Tar

Building

This project uses 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

  '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:

{
  -- 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

-- <leader>pp to toggle the player info window.
vim.keymap.set(
    "n",
    "<leader>pp",
    ":lua require('player').player_info()<CR>",
    {noremap = true},
)
-- <leader>pf to toggle the file select window.
vim.keymap.set(
    "n",
    "<leader>pf",
    ":lua require('player').file_select()<CR>",
    {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 <ENTER> 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.

require('player').play(<song name>)

Controlling pause/resume.

require('player').pause()
require('player').resume()

Controlling volume.

require('player').volume_up()
require('player').volume_down()

Open control windows.

-- 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

player-nvim-demo-small.mp4

Known issues

• Audio playback on WSL is not great and sometimes becomes very choppy. ref