Skip to content
niklas-ePublic

About

A lean piano practice app

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Piano Practice

Early work in progress — many features are not built yet.

A lean piano practice app: technical exercises and theory, nothing else.

Most practice apps bury the practice under subscriptions, ads, and accounts — and you end up juggling several of them to cover the basics. This is the opposite: one place for exercises and theory, no fluff.

The app is live at https://piano.niklas-e.fi/

Open source and free access

Piano Practice will remain open source, with the complete source of each official release and hosted version available without charge. Access to the official app will stay free while it operates. Hosting may be limited or discontinued if it becomes unsustainable; existing open-source rights and source-availability obligations still apply.

Local Development

Install dependencies:

pnpm install

Run the dev server:

pnpm dev

Build static output:

pnpm build

Sheet Music

The Sheet Music page keeps PDFs and photos of scores on the device, in the browser's IndexedDB. Nothing is uploaded. Pages can be drawn on with a pen, highlighter and eraser, and downloaded or shared with the drawings included: PDFs get the ink written into their pages as vectors (encrypted PDFs are flattened into images instead), and images are saved at full size.

Each sheet reopens on the page that was read last. Full screen shows whole pages for playing from, two side by side on landscape screens, and keeps the screen awake. Pages turn with taps on either side, swipes, or the keyboard: arrow keys, Page Up/Down and Space, which is also what Bluetooth page turner pedals send. Half-page turns, an option in full screen, show the top of the next page while the bottom of the current one is still being played. Full screen also trims the empty margins of the pages, by the same amount on every page so the music stays the same size throughout. A stylus still draws in full screen, while fingers turn the pages.

PDFs are rendered with PDF.js. Its data files (image decoders, standard fonts, colour profiles and character maps) are served from /pdfjs/ by a small Vite plugin in vite.config.ts.

Offline Support

The production build is an installable PWA. A service worker generated by vite-plugin-pwa precaches the whole app, so every page works offline after the first visit, including viewing and drawing on sheet music. PDF.js character maps, only needed for some CJK documents, are cached the first time they're used instead. The service worker is not active in pnpm dev; use pnpm build && pnpm preview to try it locally.

App icons in public/ are generated from public/favicon.svg. Regenerate them after changing the favicon:

pnpm generate-pwa-assets

Tests

Run unit tests with Node's built-in test runner:

pnpm test:unit

Run Playwright tests:

pnpm test:e2e

Run offline Playwright tests against a production build with the service worker enabled:

pnpm test:offline

Run all tests:

pnpm test

If Playwright browsers are missing, install Chromium:

pnpm exec playwright install chromium

Contributing

Bug reports, ideas and pull requests are welcome. See CONTRIBUTING.md for the short guide and one-time contributor agreement.

License

Copyright (C) 2026 Niklas Engblom

Piano Practice is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE for the full text.

The AGPL also covers running a modified version as a network service: if you host one, you must offer its users the source code of your version.

About

A lean piano practice app

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages