Fretboard

KO | EN

gitlite — search

#javascript #python #hacktoberfest #ai #llm #go #machine-learning #linux #docker #macos #pytorch #mcp #ios #open-source

(★ 66)

Customisable guitar fretboard view for iOS, tvOS and macOS with SpriteKit

Fretboard Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Fretboard

A SpriteKit-based fretboard library for iOS, iPadOS, macOS, tvOS, and visionOS.  
Built on [MusicTheory](https://github.com/cemolcay/MusicTheory) v2.0.

---

## Requirements

- Swift 5.9+
- iOS 13+ / macOS 10.15+ / tvOS 13+ / visionOS 1+

---

## Install (Swift Package Manager)

```swift
// Package.swift
.package(url: "https://github.com/cemolcay/Fretboard.git", from: "2.0.0")
```

---

## Quick start

```swift
import SpriteKit
import Fretboard

// 1. Create a model (pure geometry — no selection state)
let fretboard = Fretboard(tuning: GuitarTuning.standard, startIndex: 0, count: 12)

// 2. Create the scene
let scene = FretboardScene(fretboard: fretboard)
scene.noteDelegate = self   // optional — for synth/sampler integration

// 3. Present in an SKView (UIKit / AppKit)
skView.presentScene(scene)
// — or — in SwiftUI:
// SpriteView(scene: scene)

// 4. Show notes (scale, chord, or any set of pitches)
scene.showScale(Scale(type: .major, root: .c))

// 5. Highlight individual notes (e.g. live MIDI)
scene.highlightPitch(Pitch(noteName: .e, octave: 4))   // creates a dot if not shown
scene.unhighlightPitch(Pitch(noteName: .e, octave: 4))
```

---

## Design

The library separates **geometry** from **rendering state**:

- `Fretboard` (model) — pure data: tuning, fret range, direction. Knows nothing about selection or colors.
- `FretboardScene` (scene) — owns all visual state: which dots are shown, which are highlighted, capo-mode rendering.

This lets you combine multiple independent marking layers at once — for example, showing a scale while also reflecting live incoming MIDI notes on top of it.

---

## Model

### `Fretboard`

`Codable final class` — the consuming app owns it, reads it, writes it.

| Property | Type | Description |
|---|---|---|
| `tuning` | `Tuning` | Open-string pitches. Default: standard guitar. |
| `startIndex` | `Int` | First fret shown. 0 = open strings. |
| `count` | `Int` | Number of frets shown. |
| `direction` | `FretboardDirection` | `.horizontal` or `.vertical`. |
| `isStringsFlipped` | `Bool` | Reverses string order for the current direction. Default `false`. |
| `isFretsFlipped` | `Bool` | Reverses the fret/neck axis. Default `false`. |
| `notes` | `[FretboardNote]` | Read-only computed pitch grid. |
| `orderedStrings` | `[Pitch]` | Strings in display order (direction- and flip-aware). |
| `octaves` | `[Int]` | Unique octaves currently visible, sorted. |

Mutating any property (`tuning`, `startIndex`, `count`, `direction`, `isStringsFlipped`) rebuilds the note grid and, if the model is wired to a scene, triggers `scene.reload()` automatically via the `fretboard` `didSet`. `isFretsFlipped` is a visual-only transform — changing it requires an explicit `scene.reload()` call.

**Pitch lookup:**

```swift
// Returns every grid position whose MIDI note number matches `pitch`.
let positions = fretboard.notes(matching: Pitch(noteName: .a, octave: 2))
```

**Flipping the fretboard:**

`isStringsFlipped` reverses the **string order** (cross axis):

```swift
fretboard.isStringsFlipped = true   // triggers rebuildNotes + scene.reload() automatically
// Horizontal (default false): high E at top → low E at top when flipped.
// Vertical  (default false): high E at left → low E at left when flipped.
```

`isFretsFlipped` reverses the **fret/neck axis** (visual-only — the pitch grid is unchanged):

```swift
fretboard.isFretsFlipped = true
scene.reload()   // explicit reload required — isFretsFlipped doesn't rebuild notes
```

The convention for **not-flipped** is: nut at the *leading* edge.

| Direction | `isFretsFlipped` | Nut position |
|---|---|---|
| `.horizontal` | `false` (default) | Left — fret numbers increase left → right |
| `.horizontal` | `true` | Right — useful for **left-handed players** |
| `.vertical` | `false` (default) | **Top** — fret 1 visible at the top |
| `.vertical` | `true` | Bottom — higher frets at the top |

**Persistence:**

```swift
let data = try JSONEncoder().encode(fretboard)   // persists tuning/startIndex/count/direction/flip flags
let loaded = try JSONDecoder().decode(Fretboard.self, from: data)
scene.fretboard = loaded   // triggers scene.reload() automatically
```

---

### `Tuning`

`Codable struct { var name: String; var strings: [Pitch] }` — uniform for built-ins and custom:

```swift
// Built-in
fretboard.tuning = GuitarTuning.standard       // E2 A2 D3 G3 B3 E4
fretboard.tuning = BassTuning.standard4String   // E1 A1 D2 G2
fretboard.tuning = UkuleleTuning.standard       // G4 C4 E4 A4

// All built-in guitar tunings
let allGuitar: [Tuning] = GuitarTuning.all

// Custom (persists exactly like built-ins)
let custom = Tuning(name: "Open G Slide", strings: [
    Pitch(noteName: .d, octave: 2),
    Pitch(noteName: .g, octave: 2),
    Pitch(noteName: .d, octave: 3),
    Pitch(noteName: .g, octave: 3),
    Pitch(noteName: .b, octave: 3),
    Pitch(noteName: .d, octave: 4),
])
fretboard.tuning = custom
```

---

## Scene

### `FretboardScene`

```swift
let scene = FretboardScene(
    fretboard: fretboard,
    configuration: FretboardConfiguration()   // optional
)
```

---

### Showing notes

The marking API is split by targeting:

#### Pitch — every matching position

Shows a dot at **every** board position whose MIDI number matches the pitch.
Use this for scales, chords, and any display where all octave positions should light up.

```swift
scene.showPitch(Pitch(noteName: .c, octave: 4))          // all C4s on the neck
scene.showPitches([c4, e4, g4])

scene.hidePitch(Pitch(noteName: .c, octave: 4))
scene.clearNotes()     // removes shown set; live highlights survive as transient
scene.removeAllNotes() // unconditional wipe
```

**Theory conveniences** (expand across all visible octaves automatically):

```swift
scene.showScale(Scale(type: .major, root: .c))
scene.showChord(Chord(type: .dominant7, root: .g))
```

#### Note — one exact string + fret position

Shows a dot at **one specific** string+fret. Use this for CAGED boxes, chord voicings, and
any display where the physical fingering matters — not just which pitch sounds.

`FretboardNote` values come from `fretboard.notes` or `fretboard.notes(matching:)`.

```swift
scene.showNote(specificFretboardNote)
scene.showNotes(boxNotes)   // a set of specific positions

scene.hideNote(specificFretboardNote)
```

**Chord shape example:**

```swift
// Show only the notes of one specific G major open chord voicing:
let voicingIDs = ["5-2", "4-2", "3-0", "2-0", "1-0", "0-3"]  // "stringIndex-fretIndex"
let voicingNotes = fretboard.notes.filter { voicingIDs.contains($0.id) }
scene.showNotes(voicingNotes)
```

---

### Highlighting notes

Highlighting is independent of the shown set — used for user presses and live MIDI equally.

```swift
// Pitch-based (highlights every matching position)
scene.highlightPitch(Pitch(noteName: .e, octave: 4))   // creates transient dot if not shown
scene.unhighlightPitch(Pitch(noteName: .e, octave: 4)) // removes transient dots; dims shown ones

// Position-based (highlights exactly one string+fret)
scene.highlightNote(specificFretboardNote)
scene.unhighlightNote(specificFretboardNote)
```

A highlighted dot reverts to normal appearance on `unhighlight…` but is **not** removed if it was part of the shown set.

**Scale + live MIDI at the same time:**

```swift
scene.showScale(Scale(type: .major, root: .c))

func midiNoteOn(pitch: Pitch) {
    scene.highlightPitch(pitch)   // off-scale notes get a transient dot
}
func midiNoteOff(pitch: Pitch) {
    scene.unhighlightPitch(pitch)
}
```

---

### Per-note styling — `FretboardNoteStyle`

Every show/highlight call accepts an optional `FretboardNoteStyle`. The style overrides
specific visual properties for those dots; `nil` fields inherit from the configuration
default, which in turn inherits from the library's built-in defaults.

**Resolution order:**  
`per-note override → config.noteStyle / highlightNoteStyle → FretboardNoteStyle.defaultNote / .defaultHighlight`

```swift
public struct FretboardNoteStyle: Codable, Hashable {
    public var color: FretboardColor?       // dot fill
    public var textColor: FretboardColor?
    public var borderColor: FretboardColor?
    public var borderWidth: CGFloat?
    public var label: String?               // nil = note name, "" = hide, "♭3" = custom text
}
```

**Label semantics:**
- `nil` → use the note name (e.g. "C", "F#")
- `""` (empty) → hide the label for this dot, even if `isDrawNoteName` is on
- any other string → render that string (degree numbers, interval names, finger numbers…)

**Degree coloring example:**

```swift
let degreeColors: [Int: FretboardColor] = [
    1: FretboardColor(red: 1,   green: 0.3, blue: 0.3, alpha: 1),  // root = red
    3: FretboardColor(red: 0.3, green: 0.8, blue: 0.3, alpha: 1),  // third = green
    5: FretboardColor(red: 0.3, green: 0.5, blue: 1.0, alpha: 1),  // fifth = blue
]

for noteName in scale.noteNames {
    for octave in fretboard.octaves {
        let pitch = Pitch(noteName: noteName, octave: octave)
        if let degree = scale.degree(of: noteName) {
            scene.showPitch(pitch, style: FretboardNoteStyle(
                color: degreeColors[degree],
                label: "\(degree)"
            ))
        }
    }
}
// Scale changed → scene.removeAllNotes(); re-run loop.
```

**AUv3 MIDI in-vs-out-of-scale coloring:**

```swift
let inScale  = FretboardNoteStyle(color: FretboardColor(red: 0.2, green: 0.85, blue: 0.4, alpha: 1))
let outScale = FretboardNoteStyle(color: FretboardColor(red: 0.9, green: 0.2,  blue: 0.2, alpha: 1))

func midiNoteOn(pitch: Pitch) {
    let isInScale = currentScale.noteNames.contains(pitch.noteName)
    scene.highlightPitch(pitch, style: isInScale ? inScale : outScale)
}
```

---

### Fret inlay markers

The app decides which frets get inlays and which style; the library renders them.
Inlays survive `scene.reload()` — call these once after setup.

```swift
public enum FretInlay { case single, double }

// Standard guitar layout:
[3, 5, 7, 9, 15, 17, 19, 21].forEach { scene.showFretInlay(at: $0) }
[12, 24].forEach { scene.showFretInlay(at: $0, .double) }

// Manage individually:
scene.hideFretInlay(at: 12)
scene.clearFretInlays()
```

The dot color comes from `configuration.fretMarkerColor` (default: `.lightGray`).

---

### `FretboardConfiguration` (Codable)

#### Neck

| Property | Default | Description |
|---|---|---|
| `stringColor` | `.black` | String line color. |
| `fretColor` | `.darkGray` | Fret line color. |
| `stringLabelColor` | `.black` | String-name label color. |
| `fretLabelColor` | `.black` | Fret-number label color. |
| `backgroundColor` | `.clear` | Scene background. |
| `stringWidth` | `0.5` | String line width (pt). |
| `fretWidth` | `2` | Fret line width (pt). |
| `nutWidthMultiplier` | `2` | Nut drawn at `fretWidth × nutWidthMultiplier`. |

#### Note dot styles

| Property | Default | Description |
|---|---|---|
| `noteStyle` | `.defaultNote` | Style for all dots in their normal state. All fields optional — `nil` falls back to built-in. |
| `highlightNoteStyle` | `.defaultHighlight` | Style for all dots when highlighted. |
| `fretMarkerColor` | `.lightGray` | Fill color for fret inlay markers. |

**Built-in defaults:**

| | `defaultNote` | `defaultHighlight` |
|---|---|---|
| `color` | `.black` | orange |
| `textColor` | `.white` | `.white` |
| `borderColor` | `.clear` | `.clear` |
| `borderWidth` | `0` | `0` |

Setting properties on `noteStyle` or `highlightNoteStyle` overrides just those fields:

```swift
var cfg = FretboardConfiguration()
// Custom normal dot: dark blue fill, white text, subtle border
cfg.noteStyle = FretboardNoteStyle(
    color: FretboardColor(red: 0.15, green: 0.3, blue: 0.8, alpha: 1),
    textColor: .white,
    borderColor: FretboardColor(white: 0, alpha: 0.2),
    borderWidth: 1.5
)
// Custom highlight: vivid orange (textColor/border inherit from default)
cfg.highlightNoteStyle = FretboardNoteStyle(
    color: FretboardColor(red: 0.95, green: 0.35, blue: 0.1, alpha: 1)
)
```

Individual show/highlight calls can further override specific dots:

```swift
scene.showPitch(rootPitch, style: FretboardNoteStyle(color: .init(red: 1, green: 0.3, blue: 0.3, alpha: 1), label: "1"))
// All other pitches use config.noteStyle defaults.
```

#### Layout & labels

| Property | Default | Description |
|---|---|---|
| `fretSizing` | `.fill` | How large each fret is along the neck axis. |
| `alignment` | `.center` | Where to anchor the board when smaller than the scene. |
| `noteOffset` | `5` | Inset shrinking the dot away from cell edges (pt). |
| `isDrawNoteName` | `true` | Show note-name labels on dots globally. Per-note `label` overrides this. |
| `isDrawStringName` | `true` | Show string-name labels at the nut. |
| `isDrawFretNumber` | `true` | Show fret-number labels. |

#### Capo visualization

| Property | Default | Description |
|---|---|---|
| `isCapoModeOn` | `false` | When `true`, adjacent shown dots on the same fret merge into a capsule bar. Purely visual. |

```swift
scene.configuration.isCapoModeOn = true
```

### `FretSizing`

```swift
.fill                  // All frets fill the scene's neck axis exactly. No scroll.
.fit                   // Proportional fit: fret length = string spacing × fitAspectRatio (1.5),
                       // capped at the fill length so the board never scrolls. The board
                       // centers in both axes when smaller than the scene. Ideal for large
                       // screens (iPad) where .fill makes frets disproportionately tall.
.fixed(CGFloat)        // Fixed points per fret. Scrollable when total length overflows the scene.
.multiplier(CGFloat)   // Fraction of the scene's neck axis per fret.
```

`fitAspectRatio` is a public static constant on `FretSizing`; adjust it if you want frets wider or narrower relative to string spacing.

When content overflows, the scene enters scroll mode automatically (drag to pan — no host scroll view needed). When it fits, glide mode activates. See **Scroll vs. glide mode** in the Playback section.

### `FretboardAlignment`

```swift
.center   // Centered in the neck axis (default).
.leading  // Flush to the nut end.
.trailing // Flush to the far-fret end.
```

---

## Playback (noteOn / noteOff)

Implement `FretboardSceneDelegate` and assign it to `scene.noteDelegate`.  
The delegate fires on **user interaction only** — programmatic `showPitch` / `highlightPitch` calls do not fire it.

```swift
class MyViewController: UIViewController, FretboardSceneDelegate {
    func fretboardScene(_ scene: FretboardScene, noteOn note: FretboardNote) {
        midiOut.send(noteOn: note.pitch.midiNoteNumber, velocity: 100, channel: 0)
    }
    func fretboardScene(_ scene: FretboardScene, noteOff note: FretboardNote) {
        midiOut.send(noteOff: note.pitch.midiNoteNumber, channel: 0)
    }
}
```

- **noteOn** fires immediately on touch-down for minimum latency.
- **noteOff** fires on touch-up or cancel.
- **Polyphonic** — each finger is tracked independently, so chords and multi-touch glide both work.
- The touched fret is automatically highlighted on press and unhighlighted on release.

**Scroll vs. glide mode** — determined automatically by whether the neck content fits in the scene:

| Mode | When | Drag behaviour |
|---|---|---|
| **Glide** | Neck fits the scene (no overflow) | Dragging slides across notes — `noteOff` fires as the finger leaves a fret, `noteOn` fires as it enters the next. |
| **Scroll** | Neck overflows the scene | Dragging pans the neck after a short threshold; `noteOff` fires on conversion so notes never get stuck. |

Override at any time via `isScrollingEnabled`:

```swift
// Lock a long neck into glide mode (e.g. via a lock button)
scene.isScrollingEnabled = false

// Restore automatic behaviour
scene.isScrollingEnabled = true   // or call scene.reload() to re-detect from geometry
```

---

## FretBud

This library powers [FretBud](https://itunes.apple.com/us/app/fretbud-chord-scales-for-guitar-bass-and-more/id1234224249?mt=8), a chord & scale reference app for guitar, bass, and more.

Fretboard

Fretboard Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Fretboard

Fretboard Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README