# Recorder Tab Converter

A soprano recorder tool: a photo or scan of sheet music becomes a lead-line fingering tab, with note values, rests, and bar lines still visible. Baroque fingering is the default. A German toggle changes only F, F♯, and B♭.

The usual way to run it is one Linux AppImage. That file contains the window, the fingering charts, the sample tunes, and [oemer](https://github.com/BreezeWhite/oemer) for offline reading. Nothing is uploaded and no account is required.

## Run the AppImage

```bash
chmod +x Recorder-Tab-Converter-0.1.2.AppImage
./Recorder-Tab-Converter-0.1.2.AppImage
```

If the file will not start because FUSE is missing:

```bash
APPIMAGE_EXTRACT_AND_RUN=1 ./Recorder-Tab-Converter-0.1.2.AppImage
```

Open **Twinkle, Twinkle, Little Star** or **Ode to Joy** to see tabs immediately. Or drop a PNG, JPG, or WEBP of a page. The note list under the tab is editable. Fix a bad pitch or duration and the fingerings update. If a photo cannot be read, the app says so and does not invent notes.

## Build the AppImage

From a checkout, one command:

```bash
./scripts/build-appimage.sh
```

That installs Node packages, downloads a relocatable Python plus oemer and its ONNX models, builds the app, and writes:

```text
dist/Recorder-Tab-Converter-0.1.2.AppImage
```

The U-Net checkpoint from oemer 0.1.8 has ConvTranspose pads `[0, 0, -1, -1]`. The build rewrites those nodes to pads `[0, 0, 0, 0]` and `output_padding` `[1, 1]` before packaging. That is the same output size, and it is what current ONNX Runtime will load. The rewrite does not change fingerings.

The build needs network access the first time. The AppImage is not committed; keep it under 600MB.

## Develop in a browser

```bash
npm install
npm test
npm run dev
```

The dev server listens on [http://127.0.0.1:3847](http://127.0.0.1:3847). Photo reading uses the Python at `OEMER_PYTHON`, which `npm run dev` points at `build/python` from the AppImage build. That prefix needs CPU `onnxruntime`, not `onnxruntime-gpu`.

## Fingerings

Baroque (English) fingerings are the first choice on the [Dolmetsch Online chart for recorders in C](https://dolmetsch.com/textfingeringchart.htm) (Brian Blood). The soprano is treated in concert pitch: it sounds as written, low C is C5, and the chart stops at D7. Double holes 6 and 7, forked F, and the second-octave thumb pinch are included. Alternate fingerings on that chart are not shown. Notes outside C5–D7 are flagged instead of guessed.

Each chart is a narrow recorder drawn foot-up: holes 7 and 6 at the top, then 5 through 1, then the thumb, with the mouthpiece at the bottom. A filled hole is closed. The lead is a horizontal row of those charts, grouped by bar. An arrow after a chart is one more beat. A ×2 mark appears only when the music has a repeat.

German mode changes three notes:

- **F** — Dolmetsch’s German fingering, thumb plus holes 1–4 (`0 123 4`).
- **F♯** — thumb, 1, 2, 3, 5, 6, and half-hole 7.
- **B♭** — thumb, 1, 3, 4, and 6.

The F♯ and B♭ shapes follow the school German description in Zach VanderGraaff’s [Baroque vs German recorder](https://dynamicmusicroom.com/baroque-vs-german-recorder/) article. The octave above uses those same front holes with the Dolmetsch second-octave thumb. Every other note stays Baroque.

## Recognition limits

Reading is done locally by oemer 0.1.8 (ONNX Runtime on CPU). It looks for one lead line: the first part, the top staff, and the highest note of a chord. It misses notes, especially on phone photos, dense piano scores, and handwriting. The result is a draft in the note list. A failed read leaves that list usable and does not fill in a melody.

Lead-only means other parts, lower staves, and lower chord tones are dropped on purpose. Grace notes are omitted so the beat count stays put. Tied notes are shown separately so bar lines do not slide.