thrasher-media-service

Spotify for your personal music collection -- search, filter, and playback on demand.

TMS is one part of the Thrasher system, which forms a complete music library management system that supports tagging music in whatever way makes sense to you, and keeps ID3 tags in sync with music catalog changes so they're always your source of truth.

Linux and Mac OS are supported.

• Server/Backend
  • Build
  • fpc-ctl
• Client
• Security
  • TLS
  • PWA mode
  • Basic Auth
• Roadmap
• Attributions

Server

The server uses the same config file as thrasher-media-tool. If you haven't already, go read the first two sections of its README, to set up a skeletal config file and handle creation of your music catalog.

When you're done, you should have a config file that looks like this:

{
  "musicdir": "/PATH/TO/MUSIC",
  "server": {
    "artist_cutoff": INT
  }
}

Here are the other values that can/should be added to the server section of the configuration.

Field	Type	Description	Req
listen-if	string	The interface or hostname where the server will listen for connections and requests	Y
listen-port	int	The port on listen-if where the server will bind	Y
redir-host	string	Sets the hostname used to construct redirects and other URLs This should be set to the IP or URL that you're using access the service	Y
tls	bool	Whether tms-backend is running behind a TLS-terminating proxy, and thus if constructed URLs are https. Defaults to false.	N

Building

TMS's server component (tms-backend) runs in a container. Creating and launching the container is handled by the script fpc-ctl, which is compatible with Docker, Podman, and Apple's container.

./fpc-ctl build

The script will use the config file to get the info it needs to build and run the service, so the config must be in place to get a usable and working build.

Create user(s)

Before you can listen to music you'll need to create at least one user. This is also handled via the fpc-ctl script:

$ ./fpc-ctl user-add USER
$ ./fpc-ctl user-passwd USER PASSWD

When you load the client interface, login with the credentials you just created. That's all you need to get going, but see fpc-ctl help for the other things the script can do for you.

Client

Point a browser at the REDIR-HOST:LISTEN-PORT that you speficied to launch a player instance

• Select options in the Facets pane to queue music by facet
• Select options in the Artists pane to queue music by artist
  • Use the Filter box to narrow down the artist list
• Type a query filter in the 'Search' box to queue tracks that match the filter specified
• Click the 'Recent' button to queue the 25 most recenty added albums
• 'Clear' will unselect everything and clear the playback queue
• Click cover art to see a bigger version (and click again to dismiss)
• Type h or ? to see a keybindings popup

There is a compact, more finger-friendly mobile UI at REDIR-HOST:LISTEN-PORT/m.html.

When TLS is enabled, it can be installed as a Progressive Web App on platforms which support them.

Security

TMS itself doesn't speak HTTPS, sSo when it is run "naked" there is no security. As such, it should only be run like this on private networks.

TLS Proxy

To deploy TMS on a public network, you'll need tls enabled in the config and an SSL/TLS terminating proxy in front of it. Here's an example Nginx configuration:

server {
    server_name REDIR-HOST;
    listen LISTEN-IF:443 ssl;             # the connection server

    ssl_certificate     /etc/letsencrypt/live/HOSTNAME/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/HOSTNAME/privkey.pem;
    ssl_session_cache   shared:SSL:1m;
    ssl_session_timeout 5m;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers  on;

    location / {
        proxy_pass http://127.0.0.1:LISTEN-PORT; # assumes tms-backend is running on
                                                 # the same machine; change if not
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Attributions

• Sqlite interface: go-sqlite3

• ID3 capabilities: id3v2

• Session management: SCS

• Client audio capabilities: Howler,js

• Client notifications: AlertifyJS

All other code handwritten by me.