Having trouble with MusicPlayer? This guide covers common setup, development, and usage problems.

MusicPlayer is local-first. Your music files are read from your local public/songs directory during development. The project does not require a cloud music service, account, or authentication.

Make sure your audio files are inside:

public/
└── songs/
    ├── song1.mp3
    ├── song2.m4a
    └── ...

MusicPlayer scans this directory automatically.

The current supported formats are:

• .mp3
• .m4a
• .wav
• .flac
• .ogg
• .opus

Also check that:

• The file extension is correct.
• The file is actually a supported audio file.
• The development server has been restarted if necessary.
• The browser can normally play the audio file.

The public/songs directory is intended for your local music library and is ignored by Git.

Do not commit copyrighted music to the repository unless you have the necessary rights or permission to distribute it.

MusicPlayer uses audio metadata to obtain information such as:

• Title
• Artist
• Album
• Year
• Duration
• Embedded artwork

If a song does not contain metadata, MusicPlayer uses fallback values where possible.

For example, a file named:

my_favorite_song.mp3

may be displayed using a title derived from its filename if no title metadata is available.

Check the file's metadata using a suitable audio metadata editor and make sure fields such as Title, Artist, and Album are populated correctly.

After changing metadata, restart the development server or reload the application if the previous information is still displayed.

MusicPlayer can use embedded artwork from supported audio files.

If embedded artwork is unavailable, the application can fall back to locally provided artwork.

Make sure that:

• The image format is supported.
• The artwork is actually embedded in the audio file if you expect embedded artwork to be used.
• Any local cover file is placed in the expected public/covers directory.
• The image path is valid.

If artwork works for some songs but not others, the problem may be with the metadata or artwork stored in the individual audio files.

First make sure you are using a supported Node.js version.

Then install the project dependencies:

npm install

Start the development server:

npm run dev

The application should normally be available at:

http://localhost:3000

If the server still fails to start, check the terminal output for the specific error.

If npm install fails:

1. Make sure Node.js and npm are installed.
2. Check that your Node.js version is compatible with the project.
3. Make sure you are running the command from the repository root.
4. Try installing the dependencies again.

You can check your versions with:

node --version
npm --version

If the dependency tree has become inconsistent, you can remove node_modules and reinstall:

rm -rf node_modules
npm install

On Windows PowerShell:

Remove-Item -Recurse -Force node_modules
npm install

Avoid deleting lockfiles unless you specifically understand why doing so is necessary.

Run:

npm run type-check

This runs TypeScript without generating output.

If it reports an error:

• Read the file and line number shown in the output.
• Check for incorrect types or missing properties.
• Make sure dependencies are installed.
• Check whether the error is caused by your local changes.

Do not ignore type-check failures when preparing a pull request.

Run:

npm run lint

ESLint checks the project's JavaScript, JSX, and related source files.

If linting fails:

1. Read the reported file and line number.
2. Fix the underlying issue.
3. Run the command again.

Do not disable an ESLint rule simply to make the check pass unless there is a clear reason and the change is justified.

Run:

npm run build

The production build catches problems that may not appear during normal development.

If the build fails:

• Read the first meaningful error in the terminal.
• Check whether your recent changes caused the failure.
• Run npm run lint and npm run type-check.
• Make sure all dependencies are installed correctly.

A successful development server does not necessarily mean the production build will succeed.

Before submitting a pull request, run:

npm run lint
npm run type-check
npm run build
npm audit

Ideally, all four commands should complete successfully.

The project should also have no unexpected changes or untracked files:

git status

Music playback can behave differently between browsers because browsers have different implementations and policies around:

• Audio formats and codecs
• Autoplay
• Media loading
• Caching
• HTMLAudioElement behavior

If MusicPlayer works in one browser but not another, first try:

1. Reloading the page.
2. Checking the browser console for errors.
3. Checking whether the audio file itself plays in that browser.
4. Testing with another supported audio file.
5. Testing in another supported browser.

When reporting a browser-specific problem, include the browser name and version.

If these troubleshooting steps do not solve the problem, open a GitHub Issue in the MusicPlayer repository.

When reporting a bug, include as much useful information as possible.

1. What happened

Describe the problem clearly.

2. What you expected

Explain what you expected MusicPlayer to do.

3. Steps to reproduce

For example:

1. Start the development server.
2. Add an MP3 file to public/songs.
3. Open MusicPlayer.
4. Select the song.
5. The player does not load the audio.

4. Environment

Include:

Operating system:
Node.js version:
npm version:
Browser and version:
MusicPlayer version/commit:

5. Error messages

Include relevant terminal or browser-console errors.

For example:

npm run lint

<error output here>

Avoid posting passwords, private credentials, API keys, or other sensitive information.

If you have an idea for improving MusicPlayer, open a GitHub Issue describing:

• What you would like to add or change.
• Why the feature would be useful.
• How you imagine it working.
• Any relevant examples or screenshots.

Please check existing Issues first to avoid creating duplicates.

MusicPlayer is designed around a local music library.

Your audio files live on your own machine and are read from the project's local public/songs directory during development.

The project does not require:

• A cloud music library
• User accounts
• Authentication
• A remote music database
• Cloud storage for your songs

Please keep contributions consistent with this local-first architecture.

If possible, verify:

[ ] My music files are in public/songs
[ ] My audio format is supported
[ ] I checked the browser console
[ ] I checked the terminal output
[ ] npm run lint passes
[ ] npm run type-check passes
[ ] npm run build passes
[ ] I searched existing Issues

If the problem still exists after troubleshooting, please open an Issue with the relevant details.

Thank you for helping improve MusicPlayer! 🎧