netzpevnik – a web-based songbook that is synchronised across clients.

The problem

When a lot of people (≥4) sing along, they need multiple songbooks. Making sure everyone has a songbook that contains the respective song is hard and waiting until everyone finds the song in their PDF takes time (often leading to songs being sung in alphabetical order).

A few steps to help sing along sessions has been made: there are collections of songbook PDFs and some scripts for typesetting them in a common way and there is Bratrův zpěvník, a webpage that has a search bar and can transpose chords. Those are my main inspiration for netzpevnik, but I want to help further.

The still unresolved issues with the above approaches are:

• It is hard to add songs to the existing collections – you need to either start your own and struggle with discoverability, or convince the maintainer of the collection to add your song. (Point in case: Bratrův zpěvník has removed Slavíci z Madridu. I can see why he did that, but the song is still being sung and breaking/policing/gatekeeping song collection does not help.) I would like to switch the mindset from “I make the collection” to “we make the collection”.
• Getting the collection usually requires internet connection.
• The devices are not synchronised, so everyone needs to find the songs themselves.

Goals

The goal of netzpevnik is to solve those deficiencies. Namely:

• Synchronise multiple devices on what the current song is and with what capo (the main reason)
• Use a standard-ish¹ and light-weight format for songs
• Be able to run in an isolated environment without internet connectivity (as user-friendly as possible, though this might be a bit tricky…)
• Allow people to add their songs to the collection

Also, as a violinist, I am missing an option to add notes to the songs so at least intermezzos can be played.

¹Apart from Bratr, I want to say hello to like 2 other friends who invented their own formats that are similar but not the same. I love you, it's great that I cannot reuse your songs right away!/j (I guess there will be converters eventually…)

Later phase

Apart from what is outlined above, there could be several more features that are not the main focus now:

• Queue of songs
• Some sort of (very simple) authentication and names to fend off trolls maybe?
• Using QR codes to connect (in isolated environments there might be no DNS)

Pipe dreams

I do have those. I don't expect these things to actually happen, but I would love to hear success stories like this :-)

• It would be very friendly if the servers could run off an Android phone.
• Another instance of the problem above is in churches, and while I have no idea how usable this will turn out, it would be so awesome if someone else actually used this.

Current state

ZERO-CODE (that is modern, right? :-P)

One day, I'll put a roadmap here maybe.

Tech stack + architecture outline

Obligatory note: as this is very much a planning phase, anything here can (and will) change (against you) :3

I currently imagine 3 servers – a synchronisation server, a song repository and an optional song upload server – and 1 reference client. The servers will be quite simple, most of the logic should be done by the client which interfaces the former two servers.

The synchronisation server only handles synchronising the clients: it receives requests for song change, capo change &c. and in turn sends those updates to connected clients. It will probably be written in Elixir.

The repository is just a set of songs in a well-known format (almost certainly ChordPro²) and a bit of metadata to allow easy discovery and local search for the songs on the client. It will not be implemented – just point any HTTP server at the directory and be done! (I have not yet dug into this, it might turn out that this has to be on the same domain as the synchronisation server.) There will be some helper scripts to help manage the metadata (automatic scanning of chordpro files), the language is not yet decided.

The upload server is a way of uploading ChordPro songs to the repository, so that people can participate without having direct access to the repository filesystem. Probably there will be some invite tokens so that this will not become a general file sharing site :-) And of course, other ways of having synchronised directory (Git, Syncthing, Nextcloud, you name it) will work too. The upload server is the lowest priority of the infrastructure.

The reference client will be some sort of web application (SPA probably) for easy use by non-programmers. Its job is to be aware of the state from the sync server, get the respective songs from the repository (or cache or whatnot), apply tweaks (capo, transpositions for tuned instruments, …) and render them to the person. It will probably be the heaviest part of the stack, but that means that everything will work even on slow internet, maybe apart from the initial load. Also, it allows alternative usecases in the clients, like compiling “traditional” PDF songbooks. (The reference client will not be written in Elm, we discussed this with a friend and want to compare our implementations :-D Probably Gleam, possibly with JS/WASM libraries.)

The protocol for synchronisation server will probably be some trivial text line-based ad-hoc thing over a websocket. Maybe the upload server will eventually get an API, we will see what it would require.

For as straight-forward deployment as possible, there should be an OCI container that would just work. Also, one of the servers will serve the webapp, probably with some initial config. Discoverability of the local server might be an issue, but scanning a QR code or manually typing an IPv4 address is not the worst thing that can happen :-) (And yes, I mean it, using IPv6 without DNS is pain, and so is making sure everyone uses your DNS to use that, esp. if the person hosting netzpevnik is not a network administrator…)

²A few notes on ChordPro: I quite like the format, as it's both simple to write and read and expressive enough to capture details like what parts a song has or the notation. Unfortunately, as of ChordPro 6, there are not very many parsers for it and the specification seems to have no way of specifying repeats. On the other hand, there are several kinds of directives that are of little interest for the initial versions of netzpevnik (markup, conditional directives). This means that while I think we still should embrace the ChordPro format and not something ad-hoc (if you know about another possible format for songbooks, let me know!), netzpevnik will very likely be using a slight variation that would (1) support repeats, (2) not implement the whole ChordPro 6 specification and (3) have a different set of bugs stemming from our own parser implementation. That being said, I aim for having interoperable files (both ways), just with minor annoyances in rendering.

More ideas with low priority

There is a room for other clients (e.g. if projecting the current song to a wall has different requirements, having a native app that can be downloaded AOT). Another possible improvement would be a (web-based?) visual editor for ChordPro files that would interface the upload server, so that adding songs would be even easier. (It could also play you the chords, so you can sing along and test that the chords work :-D)

Tell me about your usecase!. Also, some of this may be a good ideas for a various programs people studying compsci need to implement anyway :-D

Licence

GPLv2-only. As of now, I am the sole author so I can negotiate :-)

Contributions are welcome (send me an email from git), please comply with SPDX/REUSE and Developer Certificate of Origin v1.1 and Sign-Off your commits to show so.

Contact

Send your issues, feature requests, success stories, patches, whatnot to netzpevnik@pokemon.ledoian.cz, thanks!