Armoniq — PDF score viewer with harmonic analysis, for iPad and Mac

The whole picture

Everything Armoniq can do

The complete list, in short: every entry is told properly further down, in its own section.

Native PDF viewersystem PDFKit: single or double page, 25–600% zoom, rotation, fit modes

Margin croppingthe white around the music goes away, with one measurement for the whole score

The stage (⌘P)one key: a screen full of music, page still, swipe to turn

Night modecrisp inversion for stages and dark rooms, without system filters

Pen, highlighter, text, eraserApple Pencil, finger or mouse; strokes down to 0.25 pt

The PDF stays intactmarkings live on a separate layer: turn it off, and the file is as before

Tempo scrollingtap the tempo and the page scrolls by itself; one touch stops it

Bluetooth pedalsAirTurn, PageFlip and the like: arrows, space, page up/down — all heard

Swipe page turnlike leafing through a book; a touch in the centre removes the bars

Chord symbol readingfrom the PDF text or with on-device OCR, scans included

Key and progressionwith a declared confidence index, degrees, cadences and song structure

Key signature read from the pagethe sharps and flats after the clef, counted staff by staff

“For beginners”chords explained: guitar and keyboard fingerings, scale, advice

Transposition on the pagetransposed symbols written over the printed ones, where your hands need them

Library = a real foldertitles, favourites, order and subfolders; the files remain yours

Authors from the cover“Words and Music by…” read from the first page, searchable and sortable

Search inside the songsfind a score from one word of a verse, with the passage shown

Splitting anthologiesfrom a 35-page PDF to the single songs, each with its title

Setliststhe songs in concert order: one button, “next”, and you play

MIDI pairingscore and keyboard registration linked both ways, SysEx included

Every MIDI brandYamaha, Korg, Roland, Ketron, Nord…: whatever the keyboard sends is recorded

MIDI lightgreen when receiving, orange when sending, red if sending fails

Two music standsturn the page on one device and the other turns too, via iCloud

Backupmarkings, titles and pairings in a single file; markings on iCloud too

Everything has a switchbehaviours are turned on and off in the settings

Data model

Three decisions that determine everything else

Before the features it pays to understand where the files end up, because the app's behaviour follows from there: what happens if you rename a PDF, if you change device, if one day you uninstall Armoniq.

The PDF is an immutable source

Armoniq opens files read-only and never rewrites them: no flattening of annotations, no conversion, no renaming. What you add — displayed title, favourite, manual order, page count, author read from the cover, MIDI pairing — lives in .armoniq-indice.json, hidden inside the folder.

Practical consequence: you can open the same PDFs with any other program, and if you remove Armoniq they remain ordinary PDF files.

The library is a real folder

Not a database inside the app. On iPad it is the app's Documents folder, exposed in Files (UIFileSharingEnabled + LSSupportsOpeningDocumentsInPlace); on Mac it is ~/Documents/Armoniq, opened in the Finder. Subfolders are the sections of the library.

Copy a PDF in from the Finder, from Files or via AirDrop and it appears in the list: the app watches the folder and coalesces re-reads, so twenty files copied together don't cause twenty scans.

Annotations are bound to the fingerprint

Strokes, highlights and writings live in .armoniq-note/, one file per score, named after the SHA-256 of the PDF — not the path, not the file name.

Practical consequence: rename the file, move it to another folder, reorganise the whole library, and the annotations stay attached to their score. It also holds after restoring from a backup.

Viewer

Stable layout: the music doesn't change size when you turn the page

The viewer is the system PDFView, which knows everything about PDFs: progressive loading, memory, print quality. Armoniq's work is in what goes around it — where to frame the page, how much to enlarge it, when to keep it still.

Automatic margin cropping. Armoniq rasterises the first pages at low resolution, estimates the paper colour with a histogram, finds the ink box and takes their union. The box is one for the whole document: page by page, the music would jump at every turn. Full-bleed pages (covers) are excluded from the measurement, and if the white to remove is under 3% the crop is cancelled.
Anchored at the top. With the margins removed the page is taller than the screen. Instead of centring it, Armoniq pins the top edge of the music to the edge of the view: the first staff line always lands in the same spot, going forward and back.
Four fit modes: whole page, double page (with the device sideways), fit to width, rotation in 90° steps for sideways or crooked scans. Zoom from 25% to 600% in 1.25× steps.
Score stays still, but only when it makes sense. If the whole page fits the available space, scrolling and elastic bounce are turned off: brushing it doesn't move it. If instead it is taller than the view — because a panel is open, or the library, or the white has been cropped — scrolling comes back, otherwise the bottom would be unreachable.
Night mode by inversion, not by filter. It is a white layer in blendMode(.difference) over the viewer: staff and text stay crisp and coloured markings stay distinguishable, without private system filters and without re-rendering the page.
The stage, with a single key (⌘P). For playing: it measures the ink of the page you are looking at and enlarges it until the writing touches the top and bottom edges, with no air around; if there is margin left at the sides, it stays centred. The page is still — no scrolling, no bouncing — you turn with a swipe, and the bars disappear. It is the only case where the measurement is per page rather than per document: filling the screen matters more than constant size, and pressing the key again puts everything back.
Automatic tempo scrolling. Tap the tempo of the song two or three times and the page scrolls down by itself at that speed; tortoise and hare fine-tune it. The first touch on the score — or the scroll wheel, on the Mac — stops everything: if the band slows down there is no button to hunt for.
Thumbnail strip attached to the viewer, to jump to the middle of a forty-page collection without scrolling through it all.

The score as a whole page — Whole page⌘0

Two pages of the score side by side — Double pagesideways only

The score fitted to the screen width — Fit to width⇧⌘W

The same score in night mode — Night mode⌘N

The same document in the four fit modes. Margin cropping is active in all four.

Annotations

A PencilKit layer over the page, saved separately

Every page of the PDF gets an overlaid canvas, handed to PDFKit through PDFPageOverlayViewProvider. Strokes are PKStroke: the same objects on iPad and Mac, so what you draw on one device looks identical on the other. The PDF content is never touched at any point.

Five tools: hand (touches pass to the PDF and you leaf normally), pen, highlighter, text, eraser. With the hand selected, the marking layer steps aside entirely.
Discrete stroke widths, not a slider. Pen: 0.25 · 0.5 · 0.75 · 1 · 1.5 · 2 · 3 · 4 · 6 · 8 · 12. Highlighter: 6 to 40. Text: 9 to 36 points. You preview the stroke before making it, and next time it comes out identical — something a continuous slider doesn't guarantee.
Six colours, rendered differently for pen and highlighter: the highlighter uses lighter, transparent tints, so the note underneath stays readable.
Draggable text: the writing sits where it is needed and moves when you grab it with a finger or the mouse. The eraser removes the whole stroke you touch, not one piece at a time.
Saved when the page leaves the scene, plus per-stroke undo. No “save” button: close the app mid-song and the markings are already on disk.
Drawing on the Mac too. On macOS PencilKit provides the model (PKDrawing, PKStroke) but not the drawing view: that one is written by hand in Armoniq, and produces strokes compatible with the iPad's.

Armoniq — tool bar

Armoniq's tool bar: hand, pen, highlight, write, eraser, six colours and the width picker

The app's real bar. It starts closed (⌘E opens it): you read far more often than you write, and an accidentally active pen leaves marks.

Chord symbol extraction

How Armoniq gets the chords out of a page

This is what separates Armoniq from a PDF reader with a theory panel bolted on. There is no song database to fish from: the chords are read from that very score, with a multi-stage chain that degrades gracefully when the page is a photocopy from 1987.

The PDF text layerIf the score comes from a notation program, the symbols are already text. PDFKit returns the page split into real lines — the chords sit on their own, above the words — and there is no need to rebuild lines from geometry.
Fallback OCRIf the text is missing (a scan) or present but yielding no chords (old embedded OCR, unreadable), the page is rasterised at 200 dpi and read with Vision in accurate mode. If the first pass finds nothing, a cleaned-up image is tried: contrast and sharpening rescue faded photocopies.
Line-by-line classificationA line counts as a “chord line” only if almost everything it contains is a chord. It is the filter that keeps out the sung text, where “la”, “mi”, “do” are Italian words and not notes.
Symbol recognitionItalian and English naming, suffixes allowed in full (m, 7, m7, maj7, m7b5, dim, aug, sus, 6, m6) and inversions like D/F#. The suffixes are listed explicitly, so “Amore” doesn't become A and “Fammi” doesn't become F.
Tolerant mode, only where legitimateOn scans, a second pass runs over the discarded words forgiving the OCR's typical swaps — S↔5, o↔0, m↔rn, and above all the sharp, which is the first sign to get lost and comes back as f, t or H. This pass applies only inside lines that have already proved to be chord lines: used everywhere, it would turn the song's words into chords.
Side informationThe same reading yields the section markers (Intro, Verse, Chorus, Coda, Finale…), the metre, the tempo marking and the capo if present, each with the page where it appears.

Italian or English naming? The score decides, not a setting: only unambiguous symbols are counted — those with a suffix or an accidental — because an isolated “A”, in an Italian lyric, is a preposition.

Armoniq — “Getting started”

The beginners' panel: chords with guitar fingering, keyboard and the notes that make them

The “Getting started” panel: every chord that was read is shown on the instrument — fretboard grid and keyboard — with the notes that make it.

“Getting started” panel	What it shows
Guitar fingering	One fret per string, sixth to first, with open and muted strings. The open shapes are tabulated; everything else is built as a barre by moving the E or A shape along the neck.
Keyboard	One octave with the chord's keys lit and the notes computed from intervals, not memorised.
Learn these first	The chords hardest to play, ordered by frequency in the song: it only makes sense for guitar, and that is where it appears.
Suggested scale	The scale that covers nearly the whole song, with numbered degrees.
Traps	The out-of-key chords, with the scale that resolves them, explained in words.
Instrument shown	Guitar, keyboard or both: keyboard-only players take the neck off the screen.

Harmonic analysis

Key by scoring, with the uncertainty declared

One thing on the page is actually written: the key signature. Armoniq reads it from the image of the first drawn page — it finds the staves, skips the clef and counts the printed sharps or flats, and the staves vote among themselves; it copes with faded photocopies too, thanks to a second, more forgiving black threshold. The signature only names a pair, though (a major key and its relative minor), and says nothing about songs that modulate: to pick the centre, Armoniq still puts all 24 keys in competition (12 tonics × major/minor) and gives each a score over the chords it read. The two keys that carry the printed signature start with an advantage.

Criterion	Points
Diatonic root in the candidate key	+2
…and with the expected quality (major/minor)	+1.5
Chord foreign to the key	−1.5
Dominant seventh on the V degree	+2
The song opens on the tonic	+2
The song closes on the tonic (+2 if the mode matches)	+3

The score alone is not enough, and Armoniq doesn't pretend otherwise: next to the key there is a confidence verdict — sure, likely, uncertain — with the reasons in the open.

Sample too small: fewer than 6 chords or fewer than 3 distinct roots, and the answer is declared a hypothesis.
Share of in-key chords under 70%: either the song modulates, or some symbol was read wrong — and it says which of the two to suspect.
Gap from the runner-up under 12%: the alternative is shown too. If the runner-up is the relative, though, it is not an error but the same scale: the app explains it instead of flagging a problem.
Signature read and declared: when the printed signature confirms the key, the panel says so (“4♯ in the signature”); when it contradicts it, the doubt is written in the open, with the pair of keys the signature would call for. And like every behaviour, the reading has its own switch in the settings.
“Lost accidentals” hypothesis: on scans the ranking is redone pretending the sharps were eaten by the print. If a more convincing key comes out, it is offered as a suspicion — without rewriting the symbols that were read. It only steps in when the key signature could not be read: once the signature is there, the suspicion is no longer needed.

The rest of the panel: recurring progression with the degrees in Roman numerals and the progression's name when it is a recognisable one (I–VI–IV–V, I–V–VI–IV, II–V–I…); weight of every chord and count of V→I cadences; harmonic rhythm as chords per line; song structure with the page of every section; transposition of the whole analysis into another key, which changes only the reading in the panel and doesn't touch the score.

And the transposition can be taken onto the page: Armoniq looks for where every symbol is printed — scanning the drawn page, whole first and then in bands, because the symbols are tiny compared to the sheet — and writes the transposed symbol exactly on top, in blue, on a white veil covering the old one (or beside it, your choice). Your hands find the chord where they expect it: above the right note, not in a separate table. You change the transposition from the bar, − and +, and the page rewrites before your eyes. It is a layer resting on top, like the pen's markings: turn it off, and the PDF is as before.

Armoniq — “Harmony”

The harmony panel: key, chords with degrees, metre, cadences, progression

The “Harmony” panel. It opens in the lower band and the score stays visible above: you compare the degree with what is printed on the staff without closing anything.

Library

No limit on quantity, because there is no catalogue to maintain

The list is the content of the folder, re-read when the folder changes. There is no import, no internal archive to keep in sync with the disk, and therefore nothing that can diverge.

Displayed title decoupled from the file name. Change the title in the list and the PDF on disk keeps its name: whoever organised files by code or order number doesn't have to give up reading them in plain words.
Authors read from the cover. Armoniq recognises the publishing formulas (“Words and Music by”, “Testo e Musica di”, “arr. by”…) in the first lines of the first page, from the PDF text or via OCR limited to the top quarter of the page. The result becomes a searchable, sortable field — cleaned of publisher, dates and copyright.
Search over title, author and file name — and, if you ask, inside the songs' words: one button reads every score's lyrics (from the PDF text layer, or with OCR where there is none) and indexes them. From then on you type “Giovanna” and find the song even if the title escapes you: the list shows the piece of verse where the word is written. Sorting by title, author, date of arrival or manual; favourites; navigable subfolders.
Honest deletion. On Mac the file goes to the Bin and is recoverable; on iPad the app's folder has no bin, and the app says so instead of promising a recovery that doesn't exist.
Library pin: on the Mac, with a wide window, the column stays open while you read; on iPad it slides away by itself to leave the whole screen to the music. Both behaviours are switches.

Armoniq — library

Armoniq's library with folders, favourites and search

The two entries at the top were two collections in a single PDF each: they are now 16 and 37 independent scores, produced by the automatic split.

Splitting collections

From a 35-page anthology to 16 independent PDFs

Anthologies are awkward to play from: to reach the song you need you scroll half a book, and all the songs share one title, one favourite, one analysis. On PDFs with many pages Armoniq offers to split them, and to do it it uses two independent signals.

The index, wherever it is. Lines like “1. La fisarmonica di Stradella … P. Conte … Pag. 4” provide correctly written titles and authors, with the printed page numbers mapped to the PDF's real ones.
The real cut points come instead from the titles printed at the top of pages: they are set in a larger size than everything else, and beneath them the first staff starts lower to make room. That double clue tells a song's first page from its continuations.
Staff recognition. The page is rasterised in greyscale at 100 dpi; dark lines at least 42% of the width are sought (tolerating short gaps), then checked to sit in groups of adjacent equidistant lines. At least two groups ⇒ it is a page of music. Covers, indexes and advertising pages have none and stay out of the split.
Editable preview. Before anything is written you see the proposed list — title, author, page range — and the titles can be fixed by hand. Until you confirm, no file is created.
Non-destructive operation. The original collection stays where it is; the new PDFs land in a folder named after the collection, numbered in order, with title and author already recorded in the index without having to re-read them.

Split the collection

16 songs recognised — titles from the index, cuts from the titles printed on the pages.

La fisarmonica di StradellaP. Conte · pages 2–4
Questa sporca vitaP. Conte · pages 5–6
AliceF. De Gregori · pages 7–8
Niente da capireF. De Gregori · pages 9–10
Le tue mani su di meA. Venditti · pages 11–12
Le cose della vitaA. Venditti · pages 13–14
Ciao uomoA. Venditti – E. Giuliani · pages 15–16
Roma capocciaA. Venditti · pages 17–18

Pages 1 and 35 excluded: no staff detected (cover and index).

The preview that precedes the split. Every row is editable before confirming.

Live use

Behaviours designed for when your hands are busy

On the Mac you prepare: you import, split, annotate, study the harmony. On the iPad, in the evening, only the score must remain — and every gesture has to work without aiming at a small target.

Swipe page turnHorizontal swipe on the score: left goes forward, right goes back. No button to centre. The single tap waits for PDFKit's double tap (which zooms) to give up, so the first of the two beats doesn't already turn the page.

Touch in the centreHides the bars and leaves only the music; the page number stays translucent at the bottom, if you want it. Another touch in the centre and they return.

OrientationPortrait shows the whole page, sideways two pages side by side. The double page is available only sideways — anywhere else it would be unreadable — and the button says so instead of sitting there disabled with no explanation.

On the Mac, no fingerClick the centre to hide the bars, two-finger swipe on the trackpad to turn, scroll wheel disabled when the page must stay still. Every command also has its keyboard shortcut.

Bluetooth pedalPage-turning pedals (AirTurn, PageFlip and the like) present themselves as keyboards, and every brand sends a different key: arrows, space, page up and down. Armoniq listens to them all, with no configuration: you flip the switch and play with your hands on the instrument.

The setlistYou prepare it at home: pick the songs from the library and drag them into concert order. In the evening one button remains — next song — which opens the score and, if a registration is paired, has the keyboard load it. If you open a piece out of order, the setlist catches up instead of getting lost.

Two music standsOne device leads and the other follows: turn the page on the Mac and the iPad on the stand turns too, or the other way round. Only the score's name and page number travel, via iCloud: the PDFs and the markings each stay at home.

Tempo scrollingTap the tempo, the page scrolls by itself; one touch stops it. The speed found is remembered, and adjusted on the fly with tortoise and hare.

MIDI integration · MIDI keyboard

Score and keyboard registration, linked both ways

Whoever plays an arranger keyboard has, for every song, a prepared registration: voices, styles, tempo. Armoniq ties that registration to the score, so the two recall each other — with no software in between.

Direct CoreMIDI on both platforms. No bridge, no helper app: Mac and iPad speak MIDI on their own, over cable or network. On both, the MIDINetworkSession is enabled, so a WiFi keyboard connects by itself, to the iPad as to the Mac.
Pairing by learning. No numbers to hunt in the manual: you press the button on the keyboard and Armoniq records the exact sequence that arrived. Everything the recall needs is kept — Bank Select, Program Change and the system-exclusive messages, which is where many keyboards (the Genos first of all) really write their registration changes — and at the right moment it is sent back identical, byte for byte, with ten milliseconds of breathing room between messages. Messages that arrive together are grouped after 150 ms of silence, which is how the keyboard actually sends them.
Both directions, each one optional. Open the score and the keyboard sets itself up; recall the registration from the keyboard and the paired score opens on the device. After sending, the app briefly ignores what comes back, so the keyboard's echo doesn't trigger a bounce.
The MIDI light. The keyboard button blinks with the traffic: green when a signal arrives, orange when Armoniq is sending, red when a send fails. Press a key on the keyboard and you see it beat: if it doesn't, the problem is the connection — and you know without opening any panel.
Automatic reconnection. MIDI ports come and go: when the device list changes, Armoniq reopens the inputs by itself. The pairing is saved in the library's index, so it also travels with the backup.

Which MIDI keyboard brands are supported?

All those that follow the MIDI standard — that is, in practice, all of them. Armoniq doesn't interpret any brand's naming: it records the bytes the keyboard sends when you select a memory and sends them back identical. These families are compatible with the score pairing and recall system; only the name each maker gives the same thing changes:

Yamaha	Registration Memory (Genos, PSR-SX, Tyros)
Korg	Performance and SongBook voices (Pa series)
Roland	Performance / UPS (E-A7 and similar)
Ketron	Registration (SD, Event)
Nord and others	Program, Combi, Scene — stage pianos, workstations, synths

Two conditions, the same for every brand: the keyboard must transmit something when you select a memory (often a “Transmit Program Change” switch in its MIDI settings) and must react to the same messages when it receives them.

Backup

One file, and its content is exactly what cannot be rebuilt

The PDFs are already yours and live in the folder: duplicating them would make a huge, useless file. The backup takes the work that exists nowhere else.

Content

A single .armoniq file with: all drawings and writings, indexed by the PDF's SHA-256, and the complete library index — displayed titles, favourites, manual order, authors, MIDI pairings.

Additive restore

Restoring adds and never deletes: what you have today that isn't in the copy stays in place. The previous index is kept anyway in .armoniq-indice-precedente.json, and the score open at that moment re-reads its markings at once.

Portability

Because the anchor is the file's fingerprint and not its path, the copy can be put onto another device where the same PDFs have different names or live in different folders: the markings find their score again.

Armoniq — at the bottom of the library

The Open folder, Backup and Restore buttons at the bottom of the library

Backup and restore go through the system file panel. No configuration, no service.

Settings

Every behaviour is a switch, with its factory value

Design rule: no change to the app's behaviour ships without its switch and its explanation. What looks like an improvement on paper can be a nuisance while playing — and then it must be possible to turn it off without waiting for an update. There is also “reset everything”.

Switch	Default
Score stays still — no scrolling or bounce when the whole page fits	on
One page at a time (iPad) instead of continuous scrolling	on
Swipe page turn on the score	on
Touch in the centre hides the bars	on
Trim the white margins around the music	on
Page number translucent while the bars are hidden	on
Shadow under the pages — pretty, but costs smoothness on iPad	off

Switch	Default
Writing tools open at launch	off
Panels at the bottom of the screen instead of centred windows	on
Thumbnail strip	off
Opening the library closes the panels	on
Opening a score dismisses the library	iPad yes · Mac no
Library pinned (turned on from the library itself)	off
Instrument for fingerings: guitar, keyboard or both	both

Keyboard shortcuts (Mac)

← →	Previous / next page
⌘− ⌘+	Zoom in 1.25× steps
⌘0	Fit to page
⇧⌘W	Fit to width

⌘R	Rotate 90°
⌘E	Opens and closes the writing tools
⌘N	Night mode
⌘P	The stage: a screen full of music, page still
⌘Z · ⌘,	Undo the last stroke · Settings

Requirements and details

Fact sheet

Platforms	One multiplatform SwiftUI app: iPadOS 18+ and macOS 15+, native Apple Silicon
Formats	PDF (text or scan). No proprietary format in or out
Rendering	PDFKit, continuous scroll modes; page / width / double fits; 25–600% zoom
Annotations	PencilKit — `PKStroke` compatible between iPad and Mac; Apple Pencil, finger or mouse

OCR	Vision, on device, in Italian and English; no image ever leaves the device
MIDI	CoreMIDI (UMP), Bank Select MSB/LSB and Program Change; network MIDI session on iOS
Service files	`.armoniq-indice.json`, `.armoniq-note/` folder, `.armoniq` backup
Network	No connection required for any feature, OCR and analysis included