Contributing

Contributing to MusicPlayer

Thanks for your interest in contributing. This page covers everything you need to get started.

Getting Set Up

Fork the repository on GitHub and clone your fork:

git clone https://github.com/yourusername/MusicPlayer.git
cd MusicPlayer

Set up your config:
```
cp appsettings.example.json appsettings.json
```
Then open appsettings.json and set your own API key.
Verify everything builds before making any changes:
```
dotnet build
```
If this doesn't pass cleanly, stop and fix it before continuing.

Branching

Always work on a new branch. Never commit directly to main.

git checkout -b feature/your-feature-name

Use a descriptive name that reflects what you're working on:

feature/repeat-mode
fix/playback-skipping
improvement/upload-progress-bar

Keep branches focused — one feature or fix per branch. If you find an unrelated bug while working, open a separate branch for it.

Code Conventions

General

Match the style of the surrounding code
Keep partial class files focused on their area — playback logic in the playback file, playlist logic in the playlist file, and so on
Don't leave commented-out code in pull requests

WinForms and thread safety

The API runs on a background thread. Any code that touches UI controls or NAudio must be marshalled back to the UI thread using this.Invoke(). Follow the pattern already used in the PlayerService bridge in Form1.cs:

svc.Play = () => this.Invoke(ResumePlayback);

svc.SetVolume = (v) => this.Invoke(() =>
{
    music_volume.Value = Math.Clamp(v, 0, 100);
    if (audioFile != null) audioFile.Volume = v / 100f;
});

If you add a new action to PlayerService, follow this same delegate pattern.

Adding API endpoints

Add new endpoints to the appropriate controller (PlayerController for playback/queue, RoomController for room management)
Use context.Items["IsHost"] to check the caller's role and return 403 for unauthorized actions
Update the API reference table in README.md to include your new endpoint
Make sure your endpoint shows up correctly in Swagger before submitting

Adding middleware

Register new middleware in Program.cs between builder.Build() and app.Run()
Order matters — LoggingMiddleware must always come before ApiKeyMiddleware so rejected requests still get logged
If your middleware needs to skip certain paths (like Swagger), add them to the path exclusion list at the top of InvokeAsync

Config and secrets

If you add a new config value, add it to appsettings.example.json with a placeholder value
Never commit appsettings.json — it is in .gitignore for a reason
Never hardcode secrets, IP addresses, or environment-specific values in code

Testing Your Changes

There are no automated tests yet. Before submitting, manually verify the following:

Build

dotnet build passes with no errors or warnings

Playback

Songs play, pause, stop, and resume correctly
Next and previous buttons work
Songs auto-advance when they finish
Shuffle mode works and doesn't cause jumping

API

Any endpoints you added or changed return correct responses in Swagger or Postman
Host-only endpoints return 403 when called with a guest token
Protected endpoints return 401 when called with no credentials

Phone remote

The remote page loads on a phone browser over the local network
Now playing info updates every second
Guest join flow works with a valid room code
Upload flow works and the track appears in the queue and playlist

Opening a Pull Request

Push your branch to your fork and open a pull request against main:

git push origin feature/your-feature-name

In your pull request description, include:

What the change does
Why it's needed or useful
Any tradeoffs or known limitations
Screenshots or Postman output if relevant

Pull requests that break existing functionality or skip the testing checklist above will be asked to fix those issues before merging.

Reporting Bugs

Open a GitHub issue and include:

What you expected to happen
What actually happened
Steps to reproduce the issue
Your OS and .NET version:
```
dotnet --version
```

The more detail the better — vague reports are hard to act on.

Navigation Menu