MusicDown

MusicDown is a self-hosted personal music server. You can connect to it using one of the official client app to listen to and download your audio files.

MusicDown App

iOS Android macOS (iOS app)

A simple app to easily list the music present on your MusicDown server, preview them, and download the .mp3 files directly to your smartphone or tablet.

App Store Google Play

MusicPlay App

iOS macOS

A complete streaming music player integrated with the system (background play, lyrics, track/artist lists). Allows playlist creation and offline listening without manually exporting .mp3 files (though still possible).

App Store

You can either use the example server software and host it yourself, or develop/create your own HTTP/S server (REST API).

How to use the clients with the example MusicDown server software ?

Please note that this software is a Docker image containing a Python Flask server example; although it can be used as it is, we recommend customising it to suit your needs.

The example server software only supports MP3 files with ID3 title and artist tags (if the tags are missing, it won't work).

  1. Download the MusicDown or MusicPlay app from the stores mentioned above.
  2. Download the Docker image of the example MusicDown server software on Docker Hub.
    Your server must have Docker installed
  3. Read the image overview (on Docker Hub) to know how to mount the volume and bind the needed port
  4. Place all your MP3 files in the "music" folder of your volume.
  5. Run your Docker container
    You can change the server port if needed, but the app in the container listen on the port 25250
  6. Open your chosen client app on your device.
  7. Set the server URL. Important: By default, the URL must include the /musicdown path after your server address (e.g. http://192.168.1.23:25250/musicdown). Type the password you set (the default one is "hackme"). Then press "Ok".
  8. To change the password, create a "password.txt" file containing your password in the volume used by the container.
  9. Each time you add new MP3 files on the server, press the "Reload server" button in the app.
  10. You can now use your app and enjoy your audio files.

How to create your own server software for the "MusicDown" apps ?

This section is intended for people who wish to develop/create their own server software (REST API) for "MusicDown" with appropriate endpoints.

Here is the list of endpoints needed for the client apps:

/
MusicDown MusicPlay

Must return a list of all available music in JSON format (see below) with 200 success status.

/reload
MusicDown MusicPlay

Must return a 200 success status when reload or server action finished.

/[FILE_NAME]
MusicDown MusicPlay
Where "[FILE_NAME]" is the name of the MP3 file

Must return the MP3 file to download or play with 200 success status or a 404 not found status.

/image/[FILE_NAME]
MusicDown MusicPlay
Where "[FILE_NAME]" is the name of the MP3 file

Must return the cover art image of the MP3 file with 200 success status or a 404 not found status.

/lyrics/[FILE_NAME]
MusicPlay
Where "[FILE_NAME]" is the name of the MP3 file

Must return the lyrics in raw text format with 200 success status or a 404 not found status.

Please note that you can also return an unauthorized 401 status for all endpoints if the password sent as a parameter to the "GET" request does not match the password defined by the server.

Here is the JSON format needed for the / endpoint

[
  {
    "artist": "Artist name",
    "path": "demo_music.mp3",
    "title": "Music title"
  },
  ...
]

Troubleshooting and FAQ using the example server

I can not access my music files via the app.

Make sure you have access to the server (e.g. you may need to be on the same network as the server).

I do not have any music shown in the app.

Make sure you have reloaded the server via the app. You need to reload it each time you add new MP3 files.

It does not work

Make sure you only have valid .mp3 files in the "music" folder on the server. Your MP3 files need to have ID3 title and artist tags in it.

Can I use it over HTTPS ?

In theory, yes. But you will need to have a valid certificate.

Can I use it over internet ?

Yes, you can access it over internet if you open the ports on your router/firewall or via a VPN.

Can I use it without password ?

No, but you don't need to enter a strong password, although this is recommended.

Support

As MusicDown is a project made during my free time. There's no actual support, but you can always contact me by email (me@koizeay.com).

koizeay.com

Privacy

The MusicDown and MusicPlay apps do not collect any data.