outro_rails 0.1.0

data/lib/outro_rails/instruments/guitar/capo.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "outro_rails/instruments/guitar"
+require "outro_rails/instruments/guitar/chord_shapes"
+
+module OutroRails
+  module Instruments
+    class Guitar
+      # What the open CAGED shapes sound as when a capo is placed on a
+      # fret: capo 1 makes the C shape sound as Db, the A shape as Bb.
+      module Capo
+        MAX_FRET = 7
+        FRETS = (0..MAX_FRET).to_a.freeze
+
+        # Conventional capo-chart spelling per pitch class: flats, except
+        # F# which is more common than Gb on charts. Derived from the
+        # theory flat spellings so the tables can't drift.
+        SOUNDING_NAMES = Theory::NoteName::FLAT_NAMES
+                         .map { |name| name == "Gb" ? "F#" : name }
+                         .freeze
+
+        module_function
+
+        # The chart row for a capo fret: the five major CAGED shapes in
+        # C A G E D order, each paired with its sounding root.
+        #   chart(1) => [[<Shape :c>, Db], [<Shape :a>, Bb], ...]
+        def chart(fret, guitar: Guitar.new)
+          unless FRETS.include?(fret)
+            raise ArgumentError,
+                  "capo fret must be 0..#{MAX_FRET}, got #{fret.inspect}"
+          end
+
+          ChordShapes.for(quality: :major).map do |shape|
+            [ shape, sounding_root(shape, fret, guitar: guitar) ]
+          end
+        end
+
+        # NoteName a shape sounds as with a capo at `fret`.
+        def sounding_root(shape, fret, guitar: Guitar.new)
+          namesake_pitch_class =
+            ChordShapes.namesake_pitch_class(shape, guitar: guitar)
+
+          pitch_class = (
+            namesake_pitch_class + fret
+          ) % Theory::Interval::SEMITONES_PER_OCTAVE
+
+          sounding_name = SOUNDING_NAMES.fetch(pitch_class)
+
+          Theory::NoteName.parse(sounding_name)
+        end
+      end
+    end
+  end
+end

data/lib/outro_rails/instruments/guitar/chord_shapes.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "outro_rails/instruments/guitar"
+
+module OutroRails
+  module Instruments
+    class Guitar
+      # The library of guitar chord shapes (CAGED and friends) in standard
+      # tuning, keyed by [quality, extension].
+      #
+      # Each shape is written relative to its open position: frets are the
+      # frets you'd play for the shape's namesake chord (the :c shape is
+      # spelled as open C). A shape becomes any other root by shifting every
+      # fret up by the same offset. Shapes carry:
+      #
+      #   root_string  – the string whose note names the chord
+      #   frets        – { string => fret }, string 6 (low) .. 1 (high)
+      #   movable_omit – strings dropped when the shape is barred up the
+      #                  neck (e.g. the awkward pinky notes of the G and A
+      #                  shapes); open-position voicings keep every string.
+      #
+      # Chords without an entry here (9/11/13, altered dominants, added
+      # tones, ...) fall back to stub generation - add shapes below to
+      # bring them into the generator.
+      module ChordShapes
+        # The five CAGED families, in their conventional order.
+        CAGED_LETTERS = %w[C A G E D].freeze
+
+        # Open-chord bass extensions (slash chords for Travis picking etc.)
+        # may only reach this far up the neck.
+        OPEN_BASS_MAX_FRET = 3
+
+        # One grip in the library. See the module comment for what each
+        # field means; instances are frozen by .shape below.
+        Shape = Struct.new(:name,
+                           :root_string,
+                           :frets,
+                           :movable_omit,
+                           keyword_init: true) do
+          # Fret played on the root string in open position
+          def root_fret
+            frets.fetch(root_string)
+          end
+
+          # The grip as barred up the neck, without the omitted strings
+          def movable_frets
+            frets.reject { |string, _| movable_omit.include?(string) }
+          end
+
+          # The CAGED family this shape descends from: :am7 => "A",
+          # :d_sus2 => "D". Shape names are spelled from their namesake
+          # chord, so the first character is always the family letter.
+          def caged_letter
+            name.to_s[0].upcase
+          end
+        end
+
+        # Builder used by the SHAPES table below (which is why it precedes
+        # the constant: the table is built by calling it at load time).
+        def self.shape(name, root_string, frets, movable_omit: [])
+          Shape.new(
+            name: name,
+            root_string: root_string,
+            frets: frets.freeze,
+            movable_omit: movable_omit.freeze
+          ).freeze
+        end
+        private_class_method :shape
+
+        # The shape table itself: { [quality, extension] => [Shape, ...] }.
+        # A missing key means the generator falls back to stubs.
+        SHAPES = {
+          # Full CAGED, ordered C A G E D (order is cosmetic - voicings are
+          # sorted by neck position at generation time).
+          [ :major, nil ] => [
+            shape(:c, 5, { 5 => 3, 4 => 2, 3 => 0, 2 => 1, 1 => 0 }),
+            shape(:a, 5, { 5 => 0, 4 => 2, 3 => 2, 2 => 2, 1 => 0 }),
+            shape(:g, 6, { 6 => 3, 5 => 2, 4 => 0, 3 => 0, 2 => 0, 1 => 3 }),
+            shape(:e, 6, { 6 => 0, 5 => 2, 4 => 2, 3 => 1, 2 => 0, 1 => 0 }),
+            shape(:d, 4, { 4 => 0, 3 => 2, 2 => 3, 1 => 2 })
+          ],
+
+          # The practical minor shapes. The Cm and Gm forms exist in theory
+          # but are unplayable as grips; add them here if you ever want them.
+          [ :minor, nil ] => [
+            shape(:a_minor, 5, { 5 => 0, 4 => 2, 3 => 2, 2 => 1, 1 => 0 }),
+            shape(:e_minor, 6, { 6 => 0, 5 => 2, 4 => 2, 3 => 0, 2 => 0, 1 => 0 }),
+            shape(:d_minor, 4, { 4 => 0, 3 => 2, 2 => 3, 1 => 1 })
+          ],
+
+          # Power chords: root on string 6 and string 5 only.
+          [ :power, nil ] => [
+            shape(:e_power, 6, { 6 => 0, 5 => 2, 4 => 2 }),
+            shape(:a_power, 5, { 5 => 0, 4 => 2, 3 => 2 })
+          ],
+
+          # Dominant sevenths get the full CAGED treatment. The G7 shape
+          # keeps string 1 - it carries the seventh.
+          [ :major, :'7' ] => [
+            shape(:c7, 5, { 5 => 3, 4 => 2, 3 => 3, 2 => 1, 1 => 0 }),
+            shape(:a7, 5, { 5 => 0, 4 => 2, 3 => 0, 2 => 2, 1 => 0 }),
+            shape(:g7, 6, { 6 => 3, 5 => 2, 4 => 0, 3 => 0, 2 => 0, 1 => 1 }),
+            shape(:e7, 6, { 6 => 0, 5 => 2, 4 => 0, 3 => 1, 2 => 0, 1 => 0 }),
+            shape(:d7, 4, { 4 => 0, 3 => 2, 2 => 1, 1 => 2 })
+          ],
+
+          [ :major, :maj7 ] => [
+            shape(:cmaj7, 5, { 5 => 3, 4 => 2, 3 => 0, 2 => 0, 1 => 0 }),
+            shape(:amaj7, 5, { 5 => 0, 4 => 2, 3 => 1, 2 => 2, 1 => 0 }),
+            shape(:gmaj7, 6, { 6 => 3, 5 => 2, 4 => 0, 3 => 0, 2 => 0, 1 => 2 }),
+            shape(:emaj7, 6, { 6 => 0, 5 => 2, 4 => 1, 3 => 1, 2 => 0, 1 => 0 }),
+            shape(:dmaj7, 4, { 4 => 0, 3 => 2, 2 => 2, 1 => 2 })
+          ],
+
+          [ :major, :'6' ] => [
+            shape(:c6, 5, { 5 => 3, 4 => 2, 3 => 2, 2 => 1, 1 => 0 }),
+            shape(:a6, 5, { 5 => 0, 4 => 2, 3 => 2, 2 => 2, 1 => 2 }),
+            shape(:g6, 6, { 6 => 3, 5 => 2, 4 => 0, 3 => 0, 2 => 0, 1 => 0 }),
+            shape(:e6, 6, { 6 => 0, 5 => 2, 4 => 2, 3 => 1, 2 => 2, 1 => 0 }),
+            shape(:d6, 4, { 4 => 0, 3 => 2, 2 => 0, 1 => 2 })
+          ],
+
+          [ :minor, :'7' ] => [
+            shape(:am7, 5, { 5 => 0, 4 => 2, 3 => 0, 2 => 1, 1 => 0 }),
+            shape(:em7, 6, { 6 => 0, 5 => 2, 4 => 0, 3 => 0, 2 => 0, 1 => 0 }),
+            shape(:dm7, 4, { 4 => 0, 3 => 2, 2 => 1, 1 => 1 })
+          ],
+
+          [ :minor, :maj7 ] => [
+            shape(:am_maj7, 5, { 5 => 0, 4 => 2, 3 => 1, 2 => 1, 1 => 0 }),
+            shape(:em_maj7, 6, { 6 => 0, 5 => 2, 4 => 1, 3 => 0, 2 => 0, 1 => 0 }),
+            shape(:dm_maj7, 4, { 4 => 0, 3 => 2, 2 => 2, 1 => 1 })
+          ],
+
+          [ :minor, :'6' ] => [
+            shape(:am6, 5, { 5 => 0, 4 => 2, 3 => 2, 2 => 1, 1 => 2 }),
+            shape(:em6, 6, { 6 => 0, 5 => 2, 4 => 2, 3 => 0, 2 => 2, 1 => 0 }),
+            shape(:dm6, 4, { 4 => 0, 3 => 2, 2 => 0, 1 => 1 })
+          ],
+
+          [ :suspended_2, nil ] => [
+            shape(:a_sus2, 5, { 5 => 0, 4 => 2, 3 => 2, 2 => 0, 1 => 0 }),
+            shape(:d_sus2, 4, { 4 => 0, 3 => 2, 2 => 3, 1 => 0 })
+          ],
+
+          [ :suspended_2, :'7' ] => [
+            shape(:a7sus2, 5, { 5 => 0, 4 => 2, 3 => 0, 2 => 0, 1 => 0 }),
+            shape(:d7sus2, 4, { 4 => 0, 3 => 2, 2 => 1, 1 => 0 })
+          ],
+
+          [ :suspended_4, nil ] => [
+            shape(:a_sus4, 5, { 5 => 0, 4 => 2, 3 => 2, 2 => 3, 1 => 0 }),
+            shape(:e_sus4, 6, { 6 => 0, 5 => 2, 4 => 2, 3 => 2, 2 => 0, 1 => 0 }),
+            shape(:d_sus4, 4, { 4 => 0, 3 => 2, 2 => 3, 1 => 3 })
+          ],
+
+          [ :suspended_4, :'7' ] => [
+            shape(:a7sus4, 5, { 5 => 0, 4 => 2, 3 => 0, 2 => 3, 1 => 0 }),
+            shape(:e7sus4, 6, { 6 => 0, 5 => 2, 4 => 0, 3 => 2, 2 => 0, 1 => 0 }),
+            shape(:d7sus4, 4, { 4 => 0, 3 => 2, 2 => 1, 1 => 3 })
+          ],
+
+          [ :diminished, nil ] => [
+            shape(:a_dim, 5, { 5 => 0, 4 => 1, 3 => 2, 2 => 1 }),
+            shape(:d_dim, 4, { 4 => 0, 3 => 1, 2 => 3, 1 => 1 })
+          ],
+
+          # quality :diminished + extension '7' is symbolized m7b5.
+          [ :diminished, :'7' ] => [
+            shape(:am7b5, 5, { 5 => 0, 4 => 1, 3 => 0, 2 => 1 }),
+            shape(:dm7b5, 4, { 4 => 0, 3 => 1, 2 => 1, 1 => 1 })
+          ],
+
+          [ :diminished, :dim7 ] => [
+            shape(:adim7, 5, { 5 => 1, 4 => 2, 3 => 0, 2 => 2 }),
+            shape(:ddim7, 4, { 4 => 0, 3 => 1, 2 => 0, 1 => 1 })
+          ],
+
+          [ :augmented, nil ] => [
+            shape(:a_aug, 5, { 5 => 0, 4 => 3, 3 => 2, 2 => 2, 1 => 1 }),
+            shape(:e_aug, 6, { 6 => 0, 5 => 3, 4 => 2, 3 => 1, 2 => 1, 1 => 0 })
+          ],
+
+          [ :augmented, :maj7 ] => [
+            shape(:amaj7sharp5, 5, { 5 => 0, 4 => 3, 3 => 1, 2 => 2 }),
+            shape(:emaj7sharp5, 6, { 6 => 0, 5 => 3, 4 => 1, 3 => 1 })
+          ]
+        }.freeze
+
+        module_function
+
+        # The shapes for a chord type, or nil when none are defined.
+        def for(quality:, extension: nil)
+          SHAPES[[ quality&.to_sym, extension&.to_sym ]]
+        end
+
+        # Whether the library has shapes for a chord type.
+        def supports?(quality:, extension: nil)
+          SHAPES.key?([ quality&.to_sym, extension&.to_sym ])
+        end
+
+        # Every chord type with a shape in a CAGED family, in vocabulary
+        # order: [[quality, extension, shape], ...]. Not every type has
+        # every letter (minor has no C or G grip, sus2 only A and D).
+        def chords_for_letter(letter)
+          target = letter.to_s.upcase
+
+          SHAPES.filter_map do |(quality, extension), shapes|
+            shape = shapes.find { |candidate| candidate.caged_letter == target }
+            [ quality, extension, shape ] if shape
+          end
+        end
+
+        # [string, fret] positions playing `shape` rooted on `root`: the
+        # whole grip shifts up by the semitone distance from the shape's
+        # namesake root. Open position (offset 0) keeps every string;
+        # barred positions drop the shape's movable_omit strings.
+        def positions(shape, root, guitar: Guitar.new)
+          offset = root_offset(shape, root, guitar: guitar)
+          frets = offset.zero? ? shape.frets : shape.movable_frets
+
+          frets.map { |string, fret| [ string, fret + offset ] }
+        end
+
+        # Semitones the shape shifts up the neck to sound `root` (0..11).
+        def root_offset(shape, root, guitar: Guitar.new)
+          root_pitch_class = Theory::NoteName.parse(root).pitch_class
+          namesake_pitch_class = namesake_pitch_class(shape, guitar: guitar)
+          offset = root_pitch_class - namesake_pitch_class
+
+          offset % Theory::Interval::SEMITONES_PER_OCTAVE
+        end
+
+        # Pitch class of the note naming the shape's open-position chord
+        # (the E shape's namesake root is the open low E). Capo charts
+        # build on this too.
+        def namesake_pitch_class(shape, guitar: Guitar.new)
+          guitar.pitch_class_at(shape.root_string, shape.root_fret)
+        end
+      end
+    end
+  end
+end

data/lib/outro_rails/instruments/guitar/tunings.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module OutroRails
+  module Instruments
+    class Guitar
+      # Registry of named guitar tunings. Each Tuning carries a URL slug,
+      # a display name, its open-string notes (low to high, i.e. string 6
+      # first) and the accidental spelling that fits it best.
+      module Tunings
+        Tuning = Struct.new(:slug,
+                            :name,
+                            :notes,
+                            :prefer,
+                            keyword_init: true) do
+          # True only for the tuning we fall back to when none is given.
+          def standard?
+            slug == "standard"
+          end
+
+          # Open-string letters without octaves, low to high: %w[D A D G B E]
+          def letters
+            notes.map { |note| note.sub(/-?\d+\z/, "") }
+          end
+
+          # "Drop D - D A D G B E"
+          def label
+            "#{name} - #{letters.join(' ')}"
+          end
+
+          # Interpolates as the display name: "#{tuning}" => "Drop D"
+          def to_s
+            name
+          end
+        end
+
+        # Slug, display name, open strings (low to high), preferred
+        # accidentals for note labels on the fretboard.
+        ALL = [
+          [ "standard",       "Standard",             %w[E2 A2 D3 G3 B3 E4],       :sharps ],
+          [ "half-step-down", "Half-Step Down",       %w[Eb2 Ab2 Db3 Gb3 Bb3 Eb4], :flats ],
+          [ "perfect-fourth", "Perfect Fourth",       %w[E2 A2 D3 G3 C4 F4],       :sharps ],
+          [ "a",              "A Tuning",             %w[A1 D2 G2 C3 E3 A3],       :sharps ],
+          [ "b",              "B Tuning",             %w[B1 E2 A2 D3 F#3 B3],      :sharps ],
+          [ "c",              "C Tuning",             %w[C2 F2 Bb2 Eb3 G3 C4],     :flats ],
+          [ "c-sharp",        "C# Tuning",            %w[C#2 F#2 B2 E3 G#3 C#4],   :sharps ],
+          [ "d",              "D Tuning",             %w[D2 G2 C3 F3 A3 D4],       :sharps ],
+          [ "drop-a",         "Drop A",               %w[A1 E2 A2 D3 F#3 B3],      :sharps ],
+          [ "drop-bb",        "Drop Bb",              %w[Bb1 F2 Bb2 Eb3 G3 C4],    :flats ],
+          [ "drop-b",         "Drop B",               %w[B1 F#2 B2 E3 G#3 C#4],    :sharps ],
+          [ "drop-c",         "Drop C",               %w[C2 G2 C3 F3 A3 D4],       :sharps ],
+          [ "drop-db",        "Drop Db",              %w[Db2 Ab2 Db3 Gb3 Bb3 Eb4], :flats ],
+          [ "drop-d",         "Drop D",               %w[D2 A2 D3 G3 B3 E4],       :sharps ],
+          [ "open-c",         "Open C",               %w[C2 G2 C3 G3 C4 E4],       :sharps ],
+          [ "open-d",         "Open D",               %w[D2 A2 D3 F#3 A3 D4],      :sharps ],
+          [ "open-e",         "Open E",               %w[E2 B2 E3 G#3 B3 E4],      :sharps ],
+          [ "open-g",         "Open G",               %w[D2 G2 D3 G3 B3 D4],       :sharps ],
+          [ "celtic",         "Celtic (DADGAD)",      %w[D2 A2 D3 G3 A3 D4],       :sharps ]
+        ].map { |slug, name, notes, prefer|
+          # Instances are shared and frozen, so callers can't mutate the registry.
+          Tuning.new(slug: slug,
+                     name: name,
+                     notes: notes.freeze,
+                     prefer: prefer).freeze
+        }.freeze
+
+        # Slug => Tuning lookup table built from ALL.
+        BY_SLUG = ALL.to_h { |tuning| [ tuning.slug, tuning ] }.freeze
+
+        # Tuning assumed when the request doesn't name one.
+        DEFAULT_SLUG = "standard"
+
+        # Every tuning, in the order declared above (i.e. menu order).
+        def self.all
+          ALL
+        end
+
+        # Just the slugs, same order. Useful for route constraints and
+        # inclusion validations.
+        def self.slugs
+          ALL.map(&:slug)
+        end
+
+        # The tuning fetch falls back to for blank input.
+        def self.default
+          BY_SLUG.fetch(DEFAULT_SLUG)
+        end
+
+        # Looks up a tuning by slug; nil/blank falls back to standard.
+        # Legacy underscore slugs ('drop_d') resolve to their dashed
+        # equivalents. Raises ArgumentError on unknown slugs (pair with
+        # InvalidParamsRedirectable to turn that into a redirect).
+        def self.fetch(slug)
+          slug = slug.to_s.strip.tr("_", "-")
+          return default if slug.empty?
+
+          BY_SLUG.fetch(slug) { raise ArgumentError,
+                                      "unknown tuning #{slug.inspect}" }
+        end
+
+        # Whether slug names a known tuning. Accepts legacy underscores like
+        # fetch does, but does not treat blank as the default: include?("")
+        # is false even though fetch("") returns standard.
+        def self.include?(slug)
+          BY_SLUG.key?(slug.to_s.tr("_", "-"))
+        end
+      end
+    end
+  end
+end

data/lib/outro_rails/instruments/guitar.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "outro_rails/instruments/guitar/capo"
+require "outro_rails/instruments/guitar/chord_shapes"
+require "outro_rails/instruments/guitar/tunings"
+
+module OutroRails
+  module Instruments
+    # A guitar with a particular tuning. Strings are numbered 1 (highest
+    # pitch) to N (lowest).
+    class Guitar
+      # Open strings low to high, i.e. string 6 first.
+      STANDARD_TUNING = %w[E2 A2 D3 G3 B3 E4].freeze
+
+      # Playable fret range; 0 is the open string.
+      MIN_FRET = 0
+      MAX_FRET = 24
+
+      # Fret inlay markers.
+      SINGLE_MARKER_FRETS = [ 3, 5, 7, 9, 15, 17, 19, 21 ].freeze
+      DOUBLE_MARKER_FRETS = [ 12, 24 ].freeze
+
+      # Open-string Pitches, low to high, as given to the constructor
+      attr_reader :tuning
+
+      # Normalizes highlight positions to [string, fret] integer pairs.
+      # Accepts [string, fret] pairs or "string:fret" strings:
+      #   normalize_positions([[5, 3], '4:2']) => [[5, 3], [4, 2]]
+      def self.normalize_positions(positions)
+        Array(positions).map do |position|
+          string, fret =
+            if position.is_a?(String)
+              position.split(":", 2)
+            else
+              position.to_a
+            end
+          [ Integer(string), Integer(fret) ]
+        end
+      end
+
+      # Builds a Guitar from a named tuning: a Tunings::Tuning, a slug
+      # ("drop_d"), or nil/"" for standard.
+      #   Guitar.in_tuning("open_g") => #<Guitar D2 G2 D3 G3 B3 D4>
+      def self.in_tuning(tuning)
+        tuning = Tunings.fetch(tuning) unless tuning.is_a?(Tunings::Tuning)
+        new(tuning: tuning.notes)
+      end
+
+      # Parses the tuning into Pitches. Instances are immutable.
+      def initialize(tuning: STANDARD_TUNING)
+        @tuning = tuning.map { |note| Theory::Pitch.parse(note) }.freeze
+        freeze
+      end
+
+      # Number of strings, taken from the tuning
+      def string_count
+        tuning.size
+      end
+
+      # Open Pitch of a string, counting 1 as the highest. The tuning is
+      # stored low to high, so the index is inverted.
+      def open_pitch(string)
+        tuning.fetch(string_count - string)
+      end
+
+      # Open-string MIDI numbers keyed by string number:
+      #   { 1 => 64, 2 => 59, 3 => 55, 4 => 50, 5 => 45, 6 => 40 }
+      def open_midis
+        (1..string_count).to_h { |string| [ string, midi_at(string, MIN_FRET) ] }
+      end
+
+      # MIDI number sounded at a string and fret - one semitone per fret
+      def midi_at(string, fret)
+        open_pitch(string).midi + fret
+      end
+
+      # That note as a Pitch, spelled with sharps or flats as preferred
+      def pitch_at(string, fret, prefer: :sharps)
+        Theory::Pitch.from_midi(midi_at(string, fret), prefer: prefer)
+      end
+
+      # Pitch class (0-11) sounded at a string and fret, ignoring octave
+      def pitch_class_at(string, fret)
+        midi_at(string, fret) % Theory::Interval::SEMITONES_PER_OCTAVE
+      end
+
+      # Every [string, fret] position whose pitch class belongs to the
+      # scale, covering open strings through max_fret on every string:
+      #   guitar.positions_in(Theory::Scale.new('C')) => [[1, 0], [1, 1], ...]
+      def positions_in(scale, min_fret: MIN_FRET, max_fret: MAX_FRET)
+        positions_with_pitch_classes(scale.pitch_classes,
+                                     min_fret: min_fret,
+                                     max_fret: max_fret)
+      end
+
+      # Every [string, fret] position sounding a note (any octave):
+      #   guitar.positions_of('C') => [[1, 8], [1, 20], [2, 1], ...]
+      def positions_of(note, min_fret: MIN_FRET, max_fret: MAX_FRET)
+        pitch_class = Theory::NoteName.parse(note).pitch_class
+        positions_with_pitch_classes([ pitch_class ],
+                                     min_fret: min_fret,
+                                     max_fret: max_fret)
+      end
+
+      private
+
+      # Scans the fretboard string by string, low string number first,
+      # collecting positions matching any of the given pitch classes.
+      def positions_with_pitch_classes(pitch_classes, min_fret:, max_fret:)
+        (1..string_count).flat_map do |string|
+          (min_fret..max_fret).filter_map do |fret|
+            if pitch_classes.include?(pitch_class_at(string, fret))
+              [ string, fret ]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/outro_rails/instruments/piano.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OutroRails
+  module Instruments
+    # Piano keyboard logic.
+    module Piano
+      # Pitch classes of the naturals, i.e. the white keys of an octave.
+      WHITE_PITCH_CLASSES =
+          Theory::NoteName::NATURAL_PITCH_CLASSES.values.freeze
+
+      module_function
+
+      # Whether a MIDI number lands on a white key
+      def white_key?(midi)
+        pitch_class = midi % Theory::Interval::SEMITONES_PER_OCTAVE
+
+        WHITE_PITCH_CLASSES.include?(pitch_class)
+      end
+
+      # Whether a MIDI number lands on a black key
+      def black_key?(midi)
+        !white_key?(midi)
+      end
+
+      # Inclusive list of key hashes between two note names, low to high:
+      #   [{ midi: 48, note: 'C3', black: false }, ...]
+      def keys_between(start_note, end_note, prefer: :sharps)
+        low  = Theory::Pitch.parse(start_note).midi
+        high = Theory::Pitch.parse(end_note).midi
+        low, high = high, low if low > high
+
+        (low..high).map do |midi|
+          { midi: midi,
+            note: Theory::Pitch.from_midi(midi, prefer: prefer).to_s,
+            black: black_key?(midi)
+          }
+        end
+      end
+
+      # Display range for a collection of pitches: the first white key
+      # strictly below the lowest note through the first white key strictly
+      # above the highest, so the keyboard always has one free white key of
+      # margin on each side (and never starts or ends on a black key):
+      #   display_range(c_major.pitched_notes)       => [B3, D5] (as Pitches)
+      #   display_range(f_sharp_major.pitched_notes) => [F4, G5]
+      def display_range(pitches, prefer: :sharps)
+        midis = pitches.map { |pitch| Theory::Pitch.parse(pitch).midi }
+
+        [
+          Theory::Pitch.from_midi(next_white_key(midis.min - 1, -1),
+                                                 prefer: prefer),
+          Theory::Pitch.from_midi(next_white_key(midis.max + 1, 1),
+                                                 prefer: prefer)
+        ]
+      end
+
+      # Walks outward from a midi pitch (direction: -1 down, +1 up) until
+      # landing on a white key, to pad keyboard display ranges.
+      def next_white_key(midi, direction)
+        midi += direction until white_key?(midi)
+        midi
+      end
+
+      # Internal helper - the public surface ends at #display_range.
+      private_class_method :next_white_key
+    end
+  end
+end

data/lib/outro_rails/instruments.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "outro_rails/instruments/guitar"
+require "outro_rails/instruments/guitar/capo"
+require "outro_rails/instruments/guitar/chord_shapes"
+require "outro_rails/instruments/guitar/tunings"
+require "outro_rails/instruments/piano"
+
+module OutroRails
+  module Instruments
+    ENUM_VALUES = { piano: 0, guitar: 1 }.freeze
+
+    ALL = ENUM_VALUES.keys.map(&:to_s).freeze
+  end
+end