Welcome to MusicDB’s documentation!¶
MusicDB WebUI. Artworks blurred for copyright reasons.¶
MusicDB is a music manager with focus on remote access to your music collection using a web-based user interface. It allows you to manage an audio stream based on a song-queue. The WebUI is focusing on being a presentation of your music rather than being a database front-end.
The music can be streamed by MusicDB and can be received by all kind of players like iTunes or VLC. For streaming, MusicDB connects as source client to a local Icecast server. This allows encrypted and protected streams so that they can be send out to the internet. Your Music. Your Cloud.
The stream gets controlled by a WebUI that hides the ugliness of software behind a nice, music-oriented web front-end. Your music gets presented and is not just a database entry in a boring list of artists and albums.
With MusicDB you control a queue of music that gets streamed. There is no playlist-management and no repeating loop of songs. If you are lazy to fill the queue with new songs, a random songs get append to the queue. This random song selector does not use cryptographic randomness. It uses lots of constraints that the selection feels random. So, recently played artists, albums and songs are blocked for a specific time until they can be added again. Furthermore, only songs with a playtime within a configurable span will be append to prevent adding intros or “long-silent-songs”.
MusicDB is for people who hate all other players. If there is another music player/manager you like (Beets, iTunes, Spotify, Ampache …), you will probably hate this one ;) In the Comparison to Other Tools chapter is a comparison with tools similar to MusicDB.
The following user documentation will guide you through the installation process and the initial setup of MusicDB.
User Documentation
MusicDB has several abstraction layers shown in the following table:
Bash Scripts |
HTML Documents |
MusicDB CLI |
MusicDB WebUI |
MusicDB API |
|
MusicDB Libraries |
|
Python |
Linux Tools |
In the following chapters, the basic concepts and philosophy of MusicDB and its components are explained. Furthermore usage guides for MusicDB and how to handle its environment are provided. Those chapters are for users as well as for developers.
See the Philosophy of MusicDB chapter and Overview of MusicDB to get an idea what it is like to use MusicDB.
Concepts and Configuration
Deeper Insight for Hackers
MusicDB API¶
The MusicDB API Classes are made to be used inside MusicDB or by command line modules. These classes implement the features of MusicDB. Their input will not be perfectly checks for sanity, so do not confront those classes with the wild. Check user-inputs before applying them to these classes - This should be done in the MusicDB CLI modules. The documentation for these classes are for developer. Users may also want look at this documentation to understand whats behind the functionality.
If MusicDB has a feature, it is here. If there is no class providing a feature, the feature does not exist.
The next section lists some quick links to introductions for easy extending MusicDB. Then a section with all API modules follows
Quick Development Start¶
Here are some links to places worth reading before starting with working on the MusicDB code:
An overview of the whole MusicDB Environment: Overview of MusicDB
Adding a new column into the music database:
musicdb.lib.db.musicdbCreating a new command line module: Creating new CLI Modules
Adding a new option to the MusicDB Configuration:
musicdb.lib.cfg.musicdb
The best way to start learning how a feature works is by starting reading the API module description.
API Classes
MusicDB Libraries¶
These chapters document the low level classes and modules used by the MusicDB API classes. This documentation is important for developer. Those modules provide some abstractions mandatory for the functionality of all modules of MusicDB. When developing a new module for MusicDB, never bypass these libraries!
MusicDB Task Management Modules¶
The MusicDB task management system is used to perform several tasks on the Music Database and Music Directory triggered by the WebUI.
MusicDB Maintaining Modules¶
The MusicDB Maintaining Modules take care that the file structure, databases and configurations will stay valid. With these modules, missing information will be created and invalid settings detected. With each start of the MusicDB back-end, these modules check if the environment MusicDB is running in is still valid.
Maintain Modules
Other tools and Libraries¶
There are some external tools used by MusicDB’s modules. Whenever a method or function uses an external program, it is mentioned in the documentation.
ID3Edit(optional):Is a tool that is used by MusicDB to edit and repair ID3 Tags (no HTTPS) in mp3-files. Type
id3edit --helpfor a short help. There is no more documentation yet, sorry. Source code can be found at GitHub.FFmpeg(mandatory):Used for analyzing music files. FFmpeg is used a lot by MusicDB for collecting all kind of information (like meta data or play-time) from music files. This is a mandatory dependency.
gstreamer(mandatory):The gstreamer framework is used for providing the audio stream of music. It is used as interface to Icecast.
Icecast(optional, but highly recommended):Icecast is a streaming service that not just allows to provide an audio stream. It also come with user management and encryption so that the audio stream can be made private.
SQLite(mandatory):All databases used and maintained by MusicDB are managed via SQLite.