dj.nvim

---

dj.nvim is a DJ companion for Neovim — manage your music, queue up tracks, and (eventually) produce your own, right from the editor.

Status: early / in development. The command scaffold and setup API work today; the headline music features below are planned and not yet shipped. Expect breaking changes while the project finds its shape.

Roadmap #

Everything in this section is planned, not yet implemented.

• Playlists — create, edit, and persist playlists; reorder tracks, import from common formats, and play through your default player.
• Download from YouTube — fetch music with yt-dlp, tag it, and drop it straight into a playlist.
• Creative mode — a small studio for music production from within Neovim (sequencing, sampling, effects). The most ambitious of the three and furthest out on the roadmap.

Prerequisites #

• Neovim (0.9+)
• For planned features (not required yet):
  • yt-dlp — downloading music from YouTube
  • an audio player callable from the shell (e.g. mpv) — playback

Formatting / linting (developers):

• stylua — formatting
• luacheck — linting
• make, git

Tests auto-bootstrap plenary.nvim on first run, so you don't need to install it manually.

Install #

-- Lazy plugin spec
{
  "marco-souza/dj.nvim",
  dependencies = { "MunifTanjim/nui.nvim" },
  config = function()
    require("dj").setup()
  end,
},

Usage #

After installing and calling setup(), the :Dj user command is available. It currently exposes a hello subcommand so you can confirm the plugin loaded:

:Dj hello
" -> notifies: hello from dj.nvim!

Subcommands live in lua/dj/init.lua; add your own there following the table shape in lua/cmd.lua. As roadmap features land, they'll be exposed as subcommands (e.g. :Dj playlist ..., :Dj download ...).

Development #

make            # fmt-check + lint + tests (what CI runs)
make tests      # just the specs
make fmt        # reformat lua/

plugin.json holds the version read by the tag-release workflow; bump version to cut a release.

License #

MIT