No description
  • JavaScript 36.3%
  • Go 20.7%
  • HTML 15.3%
  • Shell 13.7%
  • CSS 13.1%
  • Other 0.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-23 16:55:07 +00:00
client css tweaks 2026-10-23 09:23:42 -06:00
cmd fixes for recent and unseen mode 2026-10-21 20:16:48 -06:00
config standalone media wip 2026-07-12 17:30:04 -06:00
docs doc updates 2026-02-13 12:19:46 -07:00
.fpc_local.sh fpc updates 2026-08-22 16:55:39 -06:00
.gitignore add go.work.sum 2026-08-22 13:43:26 -06:00
Container-media build ok 2026-08-22 14:18:51 -06:00
Containerfile build ok 2026-08-22 14:18:51 -06:00
fpcc unbreak artist filter 2026-09-01 20:48:57 -06:00
go.mod bumping catalog ver 2026-10-21 20:36:32 -06:00
go.sum bumping catalog ver 2026-10-21 20:36:32 -06:00
LICENSE Initial commit 2025-05-06 23:40:38 -06:00
media.go further tweaks for recent and unseen mode 2026-10-21 20:27:49 -06:00
README.md fpc-ctl improvements 2026-06-21 17:53:45 -06:00
RELEASE_NOTES.md doc update 2026-10-23 10:54:40 -06:00
tms.go doc/ver 2026-10-05 19:38:38 -06:00
tms.json.example oops in config file example 2026-07-11 21:30:56 -06:00

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

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

Desktop client

  • 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.

Mobile client

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

All other code handwritten by me.