Getting started
Requirements
- Node (check
.nvmrc for version)
- pnpm
Install dependencies
pnpm install
Run
pnpm start
Run in offline mode
Plays dummy local video instead of YouTube to work properly in offline environments (eg. planes).
pnpm start:mock
Run over HTTPS
pnpm start:https
The app normally runs on plain http://localhost:3000. Browsers treat localhost as a secure context, so the Service
Worker, microphone access and the clipboard all work there without any certificate setup.
HTTPS mode is only needed when you want to open the dev server from another device - most notably a phone acting as
a remote mic. Such a device reaches the app via the LAN IP (eg. 192.168.1.10:3000), which is not a secure context,
so getUserMedia would be blocked. pnpm start:https therefore both enables TLS and exposes the server on the LAN
(no need for an extra --host flag).
It serves a self-signed certificate, so the phone will show a certificate warning that you have to accept. See
this document how to generate a locally-trusted certificate and get rid of the warning.
Build for production
pnpm build
Development
By default, dummy (simulated) microphones are used. You can use whatever other mic.
Connecting remote mic to dev server
You can just copy the link and open it in a new browser tab or whole new browser - that stays on localhost and works
with the default pnpm start.
To connect an actual phone you need HTTPS mode (pnpm start:https) and to open the LAN IP link.
Over plain HTTP the phone isn't a secure context, so the browser blocks microphone access.
Note that some songs won't work (YouTube will block the access), probably due to the host being an IP.
Tip: a tunnel (eg. cloudflared tunnel --url http://localhost:3000) is an alternative that gives the phone a real,
trusted HTTPS hostname - no certificate warning, and it avoids the YouTube-blocking issue above.
E2E tests
Running against the dev server if it's running by simply running
pnpm e2e
You can run specific test and specific browser, headed or with debug like so
pnpm e2e --project="chromium" --headed --debug tests/song-list.spec.ts
It's also possible to run the tests against prod build (same as in CI) - it makes the tests run slightly faster:
cp .dev.vars.example .dev.vars
pnpm e2e:prod
For that you might want to keep following command running separately to not have the app built every time tests are run:
pnpm build:serve
Run unit tests
pnpm test
Misc docs
Documentation about specific topics can be found in docs/ folder.
Terminology:
frequency - a frequency of player's voice in HzfrequencyRecord - object containing frequency and timestamp (of the song) when it was recordedpitch - an actual sound (eg A, C, F#) as a number where 0 = C0section - either a verse (containing notes) or a "pause section" - A.K.A instrumental part of the song when nothing's sungnote - a single singable syllabe with assigned target pitch, starting beat, length and lyric. Is also one of several types (see below)distance - a number of pitches between player's note pitch and target note pitch, disregarding the octave (so for example player's note C0 has distance 0 to note's target pitch of C4). Note a tolerance can apply - eg with tolerance of 1, distance between pitches 66 and 65 will be 0 (while between 67 and 65 would be 2)playerNote - group of frequencyRecords recorded directly after eachother, matched (by time) to a note with the same distance to it. Basically represents the player sung lines shown in the game
Note types
normal - regular notestar - golden note, gives bonus pointsrap / freestyle - notes that are always hit if any singing is detected. Gives reduced points
