choonio

Remember Google Play Music?

Well, it's dead now.

I really liked it, so I made this.

Status

What is this?

This project is a local media player for desktops, using a web browser with a UI that is very similar to the Google Play Music user interface.

It uses LibVLC and vlcj to play media files on your own computer.

Screenshots and video

Here are some screenshots to give an idea of what this project is...

There are also some short videos at <a href="https://www.youtube.com/playlist?list=PL6S442tu09UCo4z6xvnp-Zh1pN9MnZf_l">YouTube</a>, including a <a href="https://www.youtube.com/watch?v=7TpvnedUEDM">two-minute video</a> showing going from scratch to cloning the project from GitHub, then building and running the application.

What this is not?

This is not (yet?) a music streaming server, although it could maybe be made into one someday.

So, no streaming to your phone or tablet.

What else?

Primarily this is a fully-functional (well, almost), suitable for everyday use, desktop media player.

In addition, it is also a technology/competence demonstration for some interesting contemporary technologies that I use for my day job:

Java
Spring Boot
Spring WebFlux
Reactor
Jetty
MongoDB
React
React Query
Material UI
Typescript
Docker

In the feature/graphql branch there is an early experimental implementation of a GraphQL server endpoint together with some simple GraphQL queries in the frontend. It uses code-generation to create custom hooks for react-query to provide access to the defined GraphQL operations.

The GraphQL UI is accessible at http://localhost:8080/query, there is no link to it in the UI presently.

Current status

This is a fully functional media player that I use for hours every day. Things are mostly complete, and what is there should be fully working.

Like a lot of software projects, this will likely never be "finished", but right now it is in pretty good shape and completely stable and usable.

There is still plenty that could be done and there may be some rough edges.

It also has to be said that currently this is more of a project for developers than end-users - what this means is that this isn't (yet?) a turnkey installation that you can just download and run - you may need to be comfortable installing your own MongoDB server or using Docker.

It could also do with an accessibility pass as well as a localisation pass.

Tests

There is a lot of code here, which ideally means a lot of tests.

The backend API server has a lot of tests with a high degree of, although not full, code coverage.

The frontend has only a modest number of representative tests, both unit-tests using Jest and some integration tests using Cypress. Frontend testing and coverage is therefore far from ideal.

Prerequisites

A goal of this project is to pretty much use the latest available versions of everything it uses.

A Java 17 runtime environment, or JDK
MongoDB 4.4.x, earlier versions are NOT supported
VLC 4.x, using vlcj 5.0.0

VLC 4.x is currently in pre-release status - you will need to build it yourself or use a nightly build from VideoLAN.

Database

This application requires the use of a MongoDB database.

You can use a pre-existing MongoDB database, a local standard installation, or a database running inside a Docker container.

You can configure the MongoDB database connection details in an application.properties or application.yaml file in the same directory that you start the application from.

For example, application.yaml:

spring:
  data:
    mongodb:
      host: localhost
      port: 27017
      database: choonio
      username: choonio-user
      password: toomanysecrets

Building and running

Note from the pre-requisites that Java 17 is required to build or run this project.

Building from sources

Clone the GitHub repository, and in the top-level directory of the project:

mvn clean install

Or if you want to build and run:

mvn clean install spring-boot:run

This will build the backend API and the frontend UI React application.

If you just want to run the project:

mvn spring-boot:run

Note however that this spring-boot goal will always build the application first, including the frontend application build using yarn, so it might take some time.

Note also that when using spring-boot:run to launch the application, which ordinarily you would not use, you must ensure your local configuration file (with at least database connection details) is present in the choonio-core directory, not the top level project directory.

Running

At the very least, you must create an application.properties or application.yaml file that specifies the MongoDB connection details.

This file must be located in the current directory when you launch the application.

After running mvn install as described above, a standalone jar file will be created:

./choonio/choonio-core/target/choonio-core-[VERSION].jar

This jar can be executed directly, or converted into an operating system service or whatever.

To execute the jar:

java -jar ./choonio-core/target/choonio-core-[VERSION].jar

Or from the same directory as the jar file:

java -jar choonio-core-[VERSION].jar

Launching the frontend user interface

Start a web browser and visit:

http://localhost:8080

The port number can be changed, see the developer notes below.

Adding your media library

Your media needs to be structured in a particular way so that it can be scanned and parsed correctly.

The required structure is rigid, at least for now. In principle this could be made smarter, but for now it must be as exactly as described below.

Configuring media root directories

To start using this application, you need to configure the full names of the directories that contain your media files.

With the application running in a web browser, use the left-hand navigation drawer to select "Settings".

This will show the application settings screen with some tabs, select the "Library" tab.

In this settings tab you can enter the full names of the directories containing your media file.

The settings are automatically saved when you tab-off or click away from the input field.

Media directory structure

A specific directory structure is expected, for example if the media root directory is "/home/music":

/home/music
/home/music/Some Cool Artist
/home/music/Some Cool Artist/Some Cool Album
/home/music/Some Cool Artist/Some Cool Album/01 Some Cool Track.mp3
/home/music/Some Cool Artist/Some Cool Album/02 Another Cool Track.mp3
/home/music/Some Cool Artist/Some Cool Album/cover.jpg
/home/music/Some Cool Artist/Another Cool Album
/home/music/Some Cool Artist/Another Cool Album/01 Yet Another Cool Track.mp3
/home/music/Some Cool Artist/Another Cool Album/cover.jpg

Within each album directory, your media files and a base cover art file.

The media files require good meta information (e.g. ID3 tags), with album name, album artist name, (track) artist name, genre, track number and so on.

Scanning media

Using the "Scan" tab, press the "Regenerate Catalog" button to scan your configured media root directories.

This scanning progress will search for media files and cover art, parse the metadata, generate the media catalog in the database, and process the cover art to generate all the art files of the v

Choonio

Install / Use

README