Building

How to build and develop MUDE Music Player locally

This guide will help you set up your local development environment for MUDE Music Player.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (version 20.x or higher)
• npm (comes with Node.js)
• MPV media player - Must be installed and available in your system PATH
• Visual Studio Code (for testing the extension)

Installing MPV

MPV is required for audio playback:

macOS

brew install mpv

Ubuntu/Debian

sudo apt update
sudo apt install mpv

Windows

Download from mpv.io and add to your PATH.

Verify MPV is installed:

mpv --version

Setting up the development environment

1. Clone the repository

   Clone the MUDE repository to your local machine:

   git clone https://github.com/mayur1377/MUDE-music-in-vscode.git
   cd MUDE-music-in-vscode
   
2. Install dependencies

   Install all required npm packages:

   npm install
   

   This will install:

   • node-mpv - MPV player wrapper
   • ytmusic-api - YouTube Music API client
   • youtube-dl-exec - yt-dlp downloader
   • TypeScript and build tools
3. Build the extension

   Compile the TypeScript source code:

   npm run compile
   

   This uses esbuild to bundle the extension into out/extension.js.

4. Open in VS Code

   Open the project in Visual Studio Code:

   code .
   
5. Launch the extension

   Press F5 in VS Code to launch the Extension Development Host.

   This opens a new VS Code window with your extension loaded.

Available scripts

The package.json defines several useful scripts:

Development scripts

# Compile for production (minified)
npm run compile

# Compile with sourcemaps for debugging
npm run compile:dev

# Watch mode (auto-recompile on changes)
npm run watch

# Lint the code
npm run lint

Build configuration

The build process uses esbuild with these settings:

• Platform: Node.js
• Target: Node 18
• Format: CommonJS
• Externals: vscode, youtube-dl-exec, node-mpv
• Output: out/extension.js

Package the extension

To create a .vsix package for distribution:

npm run package

This creates a MUDE-{version}.vsix file that can be installed in VS Code.

Development workflow

Making changes

1. Edit source files

   Make changes to files in the src/ directory.

2. Rebuild

   Run the compile command:

   npm run compile:dev
   

   Or use watch mode for automatic rebuilds:

   npm run watch
   
3. Reload the extension

   In the Extension Development Host window:

   • Press Ctrl+R (or Cmd+R on macOS) to reload
   • Or use the “Developer: Reload Window” command
4. Test your changes

   Use the extension in the Development Host to verify your changes work correctly.

Debugging

The extension includes extensive console logging:

// Example logging from src/searchYoutube.ts
console.log('[SEARCH] User entered search query:', input);
console.log('[DOWNLOAD] Starting download from URL:', url);
console.log('[PLAYBACK] Track loaded, starting playback');

View logs in:

• Developer Tools: Help > Toggle Developer Tools > Console
• Output Panel: View > Output > Select "Extension Host"

Project structure

MUDE-music-in-vscode/
├── src/                   # TypeScript source files
│   ├── extension.ts       # Extension entry point
│   ├── player.ts          # MPV player wrapper
│   ├── searchYoutube.ts   # Search and download logic
│   ├── youtube.ts         # YouTube API integration
│   ├── getRecommendations.ts
│   ├── recommendations.ts
│   ├── nextsongs.ts
│   ├── controls.ts        # Command handlers
│   ├── statusBar.ts       # UI components
│   └── searchHistory.ts
├── out/                   # Compiled JavaScript (gitignored)
├── media/                 # Extension icons
├── node_modules/          # Dependencies (gitignored)
├── package.json           # Extension manifest
├── tsconfig.json          # TypeScript configuration
└── CONTRIBUTING.md        # Contribution guidelines

Common issues

MPV not found

If you see “Failed to find MPV on your system!”:

1. Verify MPV is installed: mpv --version
2. Ensure MPV is in your system PATH
3. Restart VS Code after installing MPV

yt-dlp download errors

If downloads fail:

1. Check your internet connection
2. Verify youtube-dl-exec is installed: npm ls youtube-dl-exec
3. On Windows, ensure the binary has .exe extension

Extension not activating

If the extension doesn’t load:

1. Check the Output panel for errors
2. Verify out/extension.js was created
3. Try rebuilding: npm run compile

Testing changes

Manual testing checklist

• Extension activates without errors
• Search functionality works
• Track downloads and plays
• Playback controls (play/pause, seek, next/previous) work
• Status bar updates correctly
• Recommendations are fetched
• Auto-play next track works
• State persists across window reloads

Testing in multiple scenarios

• Test with no internet connection (should show appropriate errors)
• Test with no MPV installed (should show error message)
• Test with multiple VS Code windows open
• Test state restoration after closing and reopening VS Code

Publishing

Prepare for release

1. Update version

   Increment the version in package.json:

   {
     "version": "1.0.17"
   }
   
2. Build for production

   Run the production build:

   npm run vscode:prepublish
   
3. Package the extension

   Create the .vsix file:

   npm run package
   
4. Publish to marketplace

   Use vsce to publish:

   npx vsce publish
   

   You’ll need a Personal Access Token from Azure DevOps.

Next steps

• Read the architecture documentation to understand the codebase
• Check the contributing guide for contribution guidelines
• Join the development by fixing issues or adding features

Happy coding! 🎧