Repository Guide

Navigating Folders

A folder row ends with a right arrow (›): click it to go into the folder, and the list shows what it holds. A score row ends with a down arrow (⌄) and opens in place, below its title; opening another score closes the one that was open. Inside a folder, the path above the list shows where you are (My repertoire › Reels › …): click any folder in it to go straight back there. The "Back to …" row below it goes up one level, and so does your browser's Back button. The address names the folder you are in, so a reload, or a return from another page, brings you back to it.

Finding a score by name

The search box at the top of the repository looks through every score in your whole repertoire, not just the folder on screen — which is the point, since the folder a tune is filed in is usually the thing you have forgotten. Type any part of a title; case and accents are ignored, so "eire" finds "Éirinn". Each result shows the folder path it lives in, and clicking it takes you straight there, with the score open on its page. Clear the box to go back to browsing.

Score Summary PDF

The summary button on a folder row generates a PDF booklet: for every tune in the folder (including sub-folders) it prints a single staff line showing the opening and closing measures side by side. Use this to create a compact setlist or tune preview sheet.

Printing a Folder

The print button next to it prints full scores rather than a preview: it lists every tune in the folder and its sub-folders, all selected by default, so you can untick the ones you don't want and give the sheet a title. Short tunes share a page automatically. To print just one tune, open it and use the print button in the score toolbar instead — no list is shown there, since opening a tune already selects it.

Shared Folders

A folder marked as shared (shown with a secondary-colour badge) is visible to other users of the same share group. Shared folders appear in the repository of every member of the group. Admins manage sharing with the Share button on the folder's row, in Edit mode.

View / Edit mode

The View / Edit toggle at the top of the page controls whether creation, move, share, export, and delete controls are shown on each row. Any non-read-only account — free, subscribed, or admin — can switch to Edit mode to manage their own content; it is not an admin-only privilege, just a way to hide clutter while browsing.

Creating Folders and Scores (Edit mode)

In Edit mode, each row shows its buttons at the end of the row. The + button adds a new sub-folder or a new score directly inside the folder you are in. Type the name and press Enter; tick "Folder (instead of a score)" for a folder. A new score opens on a short starting template (X:, T: with its name, M:, L: and K: last), so you can type the music straight after the key.

Moving Items (Edit mode)

In Edit mode, the Move button on a file or folder row (a folder with an arrow) lets you pick a destination folder. You can also drag an item by the grip at the start of its controls and drop it on a folder in the list, or on the back row to move it up one level. The item and all its contents are moved immediately. This is a server-side operation and cannot be undone from the UI.

Back up, export and restore

In View mode, the Back up button at the top of the repository downloads your whole repertoire as one file, whichever folder you are in — do this regularly, and keep the file somewhere other than this device. The export button on any file or folder downloads a portable snapshot of that item and everything inside it — ABC source, comments, tags, and the attachments themselves, not just links to them — so the file is self-contained and can be carried to another device, another account, or another server. It works the same on a free account, where the export is built in the browser. In Edit mode, the Back up button becomes Restore, which reads a backup or an exported item back into the current folder, and also accepts a full account backup archive. Importing merges rather than overwrites: a folder whose name is already taken arrives beside the existing one as "Name (2)", so nothing you already have is replaced.

Restore from backup (free accounts)

Free accounts keep their data in this browser's local storage and get an automatic rolling set of local backup snapshots. In Edit mode, use the Restore from backup button in the toolbar to pick one and roll your whole repository back to it — this replaces everything currently there and cannot be undone.

Version history (subscribers)

Subscriber accounts can switch on Historical mode (the Real time / Historical toggle in the toolbar) to show a History button on every tune, folder, and media attachment, opening its full version timeline — browse, compare, restore, name, and annotate past versions. See the Score Versioning Guide for details.

Pin for offline (subscribers)

Subscriber accounts keep their repertoire on the server, so a tune is normally fetched when you open it. Pin one — or a whole folder, with a checkbox deciding whether sub-folders come too — and its notation and attachments are downloaded and kept on this device, readable with no network at all. A folder pin tells you how much it is about to download before it starts. Pinned content is read-only offline and does not refresh by itself: unpin and pin again to pull the current version down.

Preview your public profile (subscribers)

Subscriber accounts see their own name at the top of the page as a clickable button instead of plain text. Click it to preview how your public musician profile looks — set it up and choose what is visible on the Musician page, reached from your avatar in the header.

Opening a Score

Click anywhere on a score row to expand it and display the rendered sheet music. Click again to collapse. Files are loaded from the server on first open — a spinner appears briefly while the content arrives.

The four sections

An opened score is split into four collapsible sections, each with its own bar you click to fold or unfold; in Edit mode the same four appear as tabs, with the same names and in the same order. Notes holds your own remarks about the tune, written in Markdown. ABC notation is the rendered sheet music together with the playback and practice tools. Score attachments holds images and PDF files of the tune. Audio & video holds the recordings and links you have saved. The number beside Score attachments and Audio & video says how many items each holds, and a dot on the Notes tab means the tune has notes. A section whose bar is greyed out simply has nothing in it yet. If a tune is playing while you look at another tab, a Playing · Stop button beside the tabs stops it.

Multi-Tune Files

An ABC file can contain several tunes (each starting with X:). When more than one tune is present, a selector appears above the score so you can switch between them. The selected tune index is remembered per file.

Pages for a tune

A tune can point at the page of a PDF tune book, a photo or a web page. The links of the tune you are reading show as chips under the score toolbar and at the top of Audio & video. A PDF or photo chip opens the page beside the score, or beside the video or recording so you can read while it plays; on a narrow screen a Score | Page or Video | Page switch changes what you see, and the player keeps playing. To link a page, in View or Edit mode: when the tune has no page yet, + Link a page opens the score's first PDF or photo beside it (its name at the top of the page switches to another file); turn to the tune's page and tick “Page N goes with” the tune. Tunes on page N, at the top of the page and above every PDF or photo in Score attachments, names the tunes the page belongs to now; tick or untick a tune and it is saved at once, so moving a page to another tune is an untick and a tick. Read-only band and course accounts see the links but cannot change them. A web link is added under the score toolbar in Edit mode. Escape or the close button puts the page away. A link whose file was deleted shows a dashed warning; in Edit mode you can point it at another file or remove it. Replacing a PDF asks whether its links stay on the new file.

Playback

Press the Play button in the score toolbar to hear the tune. The melody is played via a soundfont synthesiser. If a backing style is configured, the full accompaniment (percussion, guitar, bass) plays alongside. Press Stop to end playback at any time.

Tempo

Adjust the playback speed with the BPM slider in the toolbar. Five preset buttons below the slider let you jump to standard speeds: Very Slow, Slow, Practice, Near, and Session. The presets adapt to the tune type — a jig uses dotted-quarter beats while a reel uses quarter beats.

Finding a recording

The Audio & video section can search YouTube for you without leaving the score — it seeds the search from the tune's title and rhythm, so most of the time the first results are already the tune you are looking at. Save one and it is attached to the score for good; there is no need to switch into Edit mode to keep it. You can also attach a recording of your own, and each take you upload is kept rather than replacing the last one.

Turning a recording into a score

Every audio attachment carries a Transcribe to ABC button in its player bar. It listens to the recording and writes out the notes it hears as ABC, shown as a rendered score with its ABC source underneath and placed on your clipboard so you can paste it straight into a new tune. The result is a starting point rather than a finished transcription. It follows a single instrument playing one note at a time, so a solo whistle, flute or fiddle comes out far closer to the truth than a band, a guitar chord or a noisy recording made in a session. A Local account gets three transcriptions in total; a Cloud account has no limit.

Reading a PDF attachment

A PDF in Score attachments opens in a reader with page controls and a search box — useful when the attachment is a whole tunebook rather than a single tune. Searching shows you every hit rather than jumping blindly to the first, and the page controls stay reachable whether or not you are in fullscreen.

Printing

The print button in the toolbar sends the tune you are currently viewing straight to the browser print dialog as a PDF — no tune picker, since opening a tune already selects it. Multi-page scores are split across pages automatically, and displayed tablature is printed too. To print several tunes at once, use the print button on a folder row instead: it lists every tune in that folder so you can choose which ones go on the sheet.

Tablature

A tablature staff can be shown beneath the standard notation, with the fingering positions for your instrument. Open the tablature settings from the score toolbar to switch it on and to pick the instrument and capo; the choice is remembered per score, so a tune you read on the mandolin keeps its tab while the rest of your repertoire does not. The tablature is computed from the ABC source and follows every edit. How it is laid out — measures per line, which side the toolbox sits on — is set once in Configuration.

ABC Source Editor

Click the Edit button in the toolbar to open the ABC source editor directly beneath the score. Edit the notation and the score re-renders as you type; clicking a note in the score jumps to its position in the source. Your work is saved automatically as you go, so nothing is lost if you navigate away. For subscribers, one editing session publishes one version in the score's history — the automatic saves in between publish nothing, so the history stays readable.

ABC notation reference

Header Fields

Every tune starts with a block of one-letter header fields, each on its own line. The essentials: X: a tune number (required, must be unique within the file), T: the title, M: the meter (e.g. 4/4, 6/8), L: the default note length (e.g. 1/8), K: the key (e.g. Dmaj, Gmix, Ador) — always the last header line, since everything after it is the tune itself. R: names the rhythm (reel, jig, waltz…) and also steers chord and harmonic-style suggestions elsewhere in this editor. Other common fields: C: composer, Q: tempo, O: origin.

Decorations, Repeats & Bar Lines

Decorations are written inside single exclamation marks right before the note they apply to, e.g. !fermata! !trill! !p! !f! !accent!. A tilde ~ before a note requests a roll (an idiomatic ornament in Irish trad). Grace notes go in curly braces before the main note, e.g. {A}B. Repeat a section with |: at the start and :| at the end; first/second endings use [1 … [2 right after a repeat mark. A double bar || simply marks a section break with no repeat.

Multi-Tune Files

When a file contains several tunes (each starting with X:), a tune selector appears at the top of the panel. Select a tune to display and edit it. Each tune has its own chord grid and playback state. Adding a new tune to the ABC source and saving makes it available in the selector automatically.

Zoom & Fullscreen

Use the Zoom In and Zoom Out buttons to scale the score notation up or down for easier reading or editing. The Fullscreen button expands the editor to fill the entire browser window — press it again or press Escape to exit.

Print & Export

The print button sends the tune currently displayed straight to the browser print dialog as a PDF — multi-page scores are split automatically. In a file holding several tunes, it prints the one selected in the tune list, not all of them. The export button opens a menu of two formats, both converted in the browser: MusicXML (.musicxml), which Sibelius, Finale, Dorico, MuseScore and most other notation software open directly, with the notes, chord symbols, repeats and endings, ornaments and lyrics; and MuseScore (.mscz), ready to open in MuseScore. In a file of several tunes, both export the one selected in the tune list.

Transpose

Use the Transpose buttons (+ and −) to shift the key of the tune up or down by semitones; the panel shows how far you are from the key as written. In Edit mode transposing changes the tune itself: the K: header and all accidentals are rewritten in the ABC source and saved, and a short message says so. In View mode, and always for a band or course login, it only changes what you see and hear — the saved tune stays as it is, and "Back to the original" returns to it. To keep both versions, "Add as a new tune" puts the original back and adds the tune in its new key at the end of the score, titled "(in F# Dorian)" for example; the tune list switches between them. On a Cloud score the first transposition in Edit mode also saves a version in History, so the original can be found again after a reload; a Local score has no history, so use "Add as a new tune" before leaving it. Transposing also updates the chord grid to the new key.

Chord Suggestions & Chord Grid

Click a note in the score to select it, then use the chord suggestion button to see chord options for that beat. The selected chord is inserted into the chord grid at the correct bar and beat. Toggle the chord grid (strum score) with the grid button to see and edit all chords across the tune. Its two buttons write the grid's chords into the ABC source or remove every chord from it again. Use Undo to remove the last inserted chord.

Harmonic Style

The harmonic style selector controls which chord families are weighted when generating suggestions. Auto detects the style from the key and rhythm. Other options include Folk, Jazz, Classical, and modal styles (Dorian, Mixolydian…). The detected style and confidence level are shown next to the selector.

Tablature

Open the tablature settings from the score toolbar to show a tablature staff beneath the standard notation, and to pick the instrument and capo. The choice is remembered per score, so only the tunes you actually read from tab get one. The tablature is computed from the ABC source and updates live as you edit; its layout — measures per line, which side the toolbox sits on, whether the computed staff sits above or below — is set once in Configuration.

MIDI Player

The MIDI player button opens a standard playback control bar with a progress scrubber and note-by-note navigation. It uses the abcjs built-in MIDI synthesiser and is useful for quickly checking a score without engaging the full backing machine.

Import a MusicXML or MuseScore file (Edit mode)

In Edit mode the import button in the score toolbar reads a notation file and turns it into ABC in the browser, nothing is uploaded. It accepts MusicXML (.xml, .musicxml, and the compressed .mxl) as exported by MuseScore, Finale, Sibelius, Dorico or a scanning tool, and MuseScore's own files (.mscx, .mscz). The converted tune is added after the tunes already in the score you have open, as a new entry in the tune list, so nothing you had is replaced; import into an empty score to start a fresh one. The score's title, comments and attachments are untouched. Long lines are wrapped to the number of bars per line set in Configuration. A file the converter cannot read leaves the score untouched and shows why under the button. Tunes found through the web search panel arrive the same way, as ABC that replaces the current source.

Warnings and Try to fix

When the notation cannot be read cleanly, a warning appears above the score saying at which line and column the problem is. Three common ones have a Try to fix button beside them, which rewrites the source for you and saves it: a tune copied from an online collection where a stray "!" is really a line break — left alone, whole bars silently disappear from the rendered score; a mid-tune change of time signature or key written without its square brackets, as "|M:4/4" instead of "|[M:4/4]", which reads as a row of puzzling "unknown character" warnings while the change itself is quietly dropped and the rest of the tune stays in the wrong metre; and a header that heads no music, which happens when a tune is pasted below a header that was already there and leaves the score showing an empty tune. If the button does not recognise the problem it changes nothing. When it does change something it does not always guess right, so look at the score afterwards: Ctrl+Z (⌘Z) in the editor undoes the change.

Bars that do not add up

When a bar holds more or less music than its time signature allows, its bar lines and everything between them turn amber on the score, and a line above it says which bar it is and by how much it is out, counted in the beat of the time signature, for example "Bar 12: 5 eighths of 6, 1 eighth missing". Bars are counted the way musicians count them: a pickup at the start is bar 0. That pickup and the incomplete bars on either side of a repeat, a double bar line or an ending are normal and are not reported. In Edit mode a short bar has a Fill with a rest button that adds the missing rest just before its bar line and saves the score, and Fill all does every short bar at once. Check the result: a rest completes the count, but the note you forgot to type is still missing. A bar that is too long has no automatic fix, because only you know which note is extra.

Composer

The Composer writes a brand-new tune for you, in a tradition, dance form and key you choose, and adds it to the current score as an extra tune without replacing anything. You are shown the tune as notation and can listen to it before deciding, so a generation you do not like costs you nothing. Open it from the Compose button in the score toolbar; the full guide is behind the ? inside that panel.

What is the Learning Machine?

The Learning Machine guides you through a structured practice workflow for any ABC tune. It focuses on two main stages — Listen and Phrase — plus an optional Ornamentation stage for Irish tunes.

Stage 1 — Listen

In the Listen stage, the tune plays at your chosen tempo so you can absorb the melody before attempting to play it. You can also enable the backing here to practise with accompaniment while keeping the full tune flow. Use the tempo slider (40–120 % of the original BPM) to slow the tune down for careful listening.

Stage 2 — Phrase

In the Phrase stage the score is split into named phrases (A1, A2, B1 …) of two or three bars, following the parts of the tune: a phrase always stops at a repeat bar, so the end of the A part is never joined to the start of the B part. A pickup note is played with the first phrase of its part, and a 2nd ending is a phrase of its own. Select one or more phrases to isolate and loop them. Enable Append Phrases to practice multiple sections back-to-back. Use Call & Response to leave a silence after each loop so you can respond on your instrument.

Stage 3 — Potential Ornaments

A third stage appears when the tune is one that takes ornaments — Irish and related repertoire. It reads the melody and shows where a long roll, a short roll, a cut, a grace note from below or a triplet would sit naturally, counted by kind: "4× Long roll", "7× Cut". Click a kind to hear only those, so you can work on one ornament at a time instead of everything at once. These are suggestions on top of the tune, never changes to it — your notation is untouched.

Phrase Complexity Indicators

Each phrase button shows a small coloured dot that indicates its difficulty: green (easy), orange (moderate), red (hard). The score is calculated from four axes — note density, rhythmic variation, melodic intervals, and ornamentation — and weighted for your selected instrument. Use this to decide which phrases to practise first.

Instrument Profile

The Instrument selector (visible in the Phrase stage) adjusts how complexity is weighted for your instrument. Fiddle emphasises bowing patterns and ornaments. Guitar weights chord-change density. Flute accounts for breath cost on large leaps. Tenor Banjo (Irish/jazz melody) weights melodic intervals and ornaments; 5-String Banjo (Scruggs/bluegrass) weights roll density. For accordion, Chromatic has full range so only bellows cost on leaps is penalised; the three diatonic systems (B/C, G/C, C#/D) heavily penalise accidentals and bellows direction changes, since chromatic notes require awkward fingerings on a bisonoric instrument. Changing the instrument instantly updates the difficulty dots on all phrase buttons.

Playability Warning & Transposition Hint

Some instruments cannot play every chromatic note. When the selected instrument has a restricted range, a warning appears listing the notes absent from the instrument and suggesting the smallest transposition (in semitones) that would make the tune fully playable. The standard 2-row Diatonic G/C accordion, for example, has no C#, D#/Eb, G#/Ab, or Bb keys — a tune containing any of these notes will trigger the warning. B/C and C#/D diatonic systems are fully chromatic and never trigger this warning.

Score Complexity

The Complexity setting controls how much of the score is shown. Skeleton shows only the most important notes (long, unornamented beats), making the tune easier to read and learn. Outline adds more rhythmic detail. Full shows the complete score. Progress through the levels as your confidence grows.

Metronome & Cursor

Enable the Metronome to hear a click track during playback. Enable Cursor to see a moving highlight on the score that follows the current note. A Tablature checkbox here shows the tab staff for this tune, exactly as the tablature settings in the score toolbar do — the two are the same switch. All three can be toggled independently at any time.

Tune Tempo Presets

When a backing style is active, five tempo presets appear in the Tempo section: Very Slow (~40 % of session speed — for very complex passages or absolute beginners), Slow (~55 % — ideal for first learning), Practice (~70 %), Near (~85 %), and Session (100 % — the standard speed for that tune type). All BPM values are adapted to the tune's beat unit (quarter note for reels/hornpipes, dotted quarter for jigs). Click any preset to set the tempo instantly.

Tempo Progression

Enable Tempo Progression (in the Phrase stage, when a backing style is active) to have the tempo advance automatically as you practice. Enabling it resets the tempo to the Very Slow preset. After the configured number of repetitions (1–10), the tempo increases by the chosen BPM step. Progression stops at each preset boundary (Very Slow → Slow → Practice → Near → Session) rather than skipping past it. The visual rail shows your current position, the five preset markers, and a chip indicating the next step. A loop counter below the rail shows how many repetitions remain before the next advance.

Standard Session Speed

The Session preset (the last of the five tempo presets) locks the tempo to the tune's standard session BPM and is equivalent to enabling Standard Session Speed. Use it for a final full-speed run-through before playing with others. Note: enabling Tempo Progression overrides this setting and resets the tempo to the Very Slow preset.