clef 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 54756cf60de8a132c3b38667cd33fdd80f4bb856d87026b916aa4018b1d515e3
+  data.tar.gz: f78c5b688a8a28952a08d701c737c9b1929cebf6caf86451f9daa0e92ca7f84d
+SHA512:
+  metadata.gz: 2e82ac741da2cdf64fc828fe4664bb1d29bd7a118c0a4bd7095c8d189cafb72be12e8fa263500135d193a467c3728cb97a4fcca5f7ef2e459189f294ef8eddb0
+  data.tar.gz: 56655953b3b5b01289b38a4e08bf80ce07024cfd13208cc15bb57059e07e4e8a6be2ee6c31ebb2879fb4b379381cd8558d4524b673bc0b2ba3451daeb8ca4f8d

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+# Clef
+
+Clef is a Ruby toolkit for building small scores with a Ruby DSL and exporting them to PDF, SVG, or MIDI.
+
+## Current Feature Set
+
+- Core score model for pitches, durations, notes, rests, chords, measures, staves, staff groups, and tempo
+- Ruby DSL via `Clef.score`
+- LilyPond-like shorthand through `play` and `notes`
+- Basic LilyPond import through `Clef::Parser::LilypondParser`
+- PDF rendering with Prawn
+- SVG rendering with Nokogiri
+- MIDI export with midilib
+- Plugin hooks around layout and rendering
+
+## Installation
+
+Clef requires Ruby 3.1 or newer.
+
+For local development:
+
+```bash
+git clone https://github.com/ydah/clef.git
+cd clef
+bin/setup
+```
+
+For PDF output with SMuFL glyphs, place `Bravura.otf` at `fonts/bravura/Bravura.otf`.
+If the font file is missing, Clef falls back to `Helvetica`.
+
+## Quick Start
+
+```ruby
+require "clef"
+
+score = Clef.score do
+  title "Twinkle Twinkle Little Star"
+  composer "Traditional"
+  tempo beat_unit: :quarter, bpm: 100
+
+  staff :melody, clef: :treble do
+    key :c, :major
+    time 4, 4
+    play "c'4 c'4 g'4 g'4 | a'4 a'4 g'2 | f'4 f'4 e'4 e'4 | d'4 d'4 c'2"
+  end
+end
+
+score.to_pdf("twinkle.pdf")
+score.to_svg("twinkle.svg")
+score.to_midi("twinkle.mid")
+```
+
+`title`, `composer`, and `tempo` are stored on the score. The current PDF and SVG renderers focus on staff content, while `tempo` is also used by MIDI export.
+
+## DSL Overview
+
+Clef's main entry point is `Clef.score`.
+
+- `staff` creates a staff
+- `staff_group(:brace)` and `staff_group(:bracket)` group staves in the score model
+- `play` splits measures on `|`
+- `play` and `notes` accept LilyPond-like tokens such as `c'4`, `r8`, and `<c' e' g'>2.`
+- `voice` gives explicit control over notes, rests, and chords
+- `lyrics` attaches lyric data to a named voice
+
+Example:
+
+```ruby
+score = Clef.score do
+  staff_group :brace do
+    staff :piano_rh, clef: :treble do
+      key :c, :major
+      time 4, 4
+      play "c'4 e'4 g'4 c''4"
+    end
+
+    staff :piano_lh, clef: :bass do
+      key :c, :major
+      time 4, 4
+
+      voice :main do
+        chord %w[c3 g3], :half
+        rest :half
+      end
+    end
+  end
+end
+```
+
+Within a `voice` block, manual builders accept scientific pitch strings such as `C4`, `F#3`, and `Bb5`. The shorthand token parser used by `play` and `notes` expects LilyPond-style pitch tokens.
+
+## LilyPond Input
+
+`Clef::Parser::LilypondParser` supports a small subset of LilyPond and turns it into a `Clef::Core::Score`.
+
+```ruby
+parser = Clef::Parser::LilypondParser.new
+
+score = parser.parse(<<~LY)
+  \clef treble
+  \key c \major
+  \time 4/4
+  { c'4 d'4 e'4 f'4 }
+LY
+
+score.to_svg("phrase.svg")
+```
+
+The current parser recognizes:
+
+- `\clef`
+- `\key` with `\major` or `\minor`
+- `\time`
+- Note, rest, chord, and bar tokens inside `{ ... }`
+
+## Plugins
+
+Clef exposes plugin hooks through `Clef.plugins`.
+
+```ruby
+class MarkerPlugin < Clef::Plugins::Base
+  def on_before_layout(score)
+    score.metadata[:prepared] = true
+  end
+end
+
+Clef.plugins.register(MarkerPlugin)
+```
+
+Available hooks:
+
+- `on_before_layout(score)`
+- `on_after_layout(layout_result)`
+- `on_before_render(renderer)`
+
+## Current Scope
+
+- PDF and SVG rendering currently cover clefs, key and time metadata, noteheads, rests, stems, accidentals, dots, chords, and simple articulation text.
+- PDF and SVG do not yet render score headers, lyric lines, ties, slurs, beams, or staff-group braces and brackets.
+- PDF, SVG, and MIDI export currently consume the first voice in each measure. The core model and IR can hold multiple voices, but full polyphonic engraving and playback are not wired into the output pipeline yet.
+- The compiler currently computes `Clef::Ir::MusicTree` and `Clef::Layout::Spacing` before rendering. `Clef::Layout::LineBreaker`, `PageBreaker`, and `BeamLayout` exist in the codebase as standalone building blocks and are covered by specs, but they are not yet integrated into PDF or SVG output.
+
+## Development
+
+Install dependencies:
+
+```bash
+bin/setup
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+bundle exec rake
+```
+
+Run an example:
+
+```bash
+bundle exec ruby examples/twinkle.rb
+```
+
+Open a console:
+
+```bash
+bin/console
+```
+
+## License
+
+MIT License.

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new(:yard)
+rescue LoadError
+  task :yard do
+    warn("YARD is not installed. Run: bundle add yard --group development")
+  end
+end
+
+task default: :spec

data/examples/bach_cello_suite.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "clef"
+
+score = Clef.score do
+  title "Cello Suite No.1 (Opening Motif)"
+  composer "J. S. Bach"
+
+  staff :cello, clef: :bass do
+    key :g, :major
+    time 4, 4
+    play "g,8 d8 b8 d8 g8 d8 b8 d8 | g,8 e8 c8 e8 g8 e8 c8 e8"
+  end
+end
+
+score.to_pdf("bach_cello_suite.pdf")

data/examples/piano_score.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "clef"
+
+score = Clef.score do
+  title "Piano Example"
+  composer "Clef Demo"
+
+  staff_group :brace do
+    staff :piano_rh, name: "Piano RH", clef: :treble do
+      key :c, :major
+      time 4, 4
+      play "c'4 e'4 g'4 c''4"
+    end
+
+    staff :piano_lh, name: "Piano LH", clef: :bass do
+      key :c, :major
+      time 4, 4
+      play "c2 g,2"
+    end
+  end
+end
+
+score.to_pdf("piano_score.pdf")

data/examples/twinkle.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "clef"
+
+score = Clef.score do
+  title "Twinkle Twinkle Little Star"
+  composer "Traditional"
+
+  staff :melody, clef: :treble do
+    key :c, :major
+    time 4, 4
+    play "c'4 c'4 g'4 g'4 | a'4 a'4 g'2 | f'4 f'4 e'4 e'4 | d'4 d'4 c'2"
+  end
+end
+
+score.to_pdf("twinkle.pdf")
+score.to_svg("twinkle.svg")
+score.to_midi("twinkle.mid")

data/examples/vocal_score.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "clef"
+
+score = Clef.score do
+  title "Vocal Example"
+  composer "Clef Demo"
+
+  staff :voice, clef: :treble do
+    key :f, :major
+    time 3, 4
+
+    voice :singer do
+      notes "a'4 bes'4 c''4"
+    end
+
+    lyrics :singer, "la-la la"
+  end
+end
+
+score.to_pdf("vocal_score.pdf")

data/fonts/bravura/README.md

@@ -0,0 +1,8 @@
+# Bravura Font Placeholder
+
+Place `Bravura.otf` here when you want SMuFL glyph rendering in PDF output.
+
+- Project: https://github.com/steinbergmedia/bravura
+- License: SIL Open Font License 1.1
+
+Clef will fall back to `Helvetica` if the file is missing.

data/lib/clef/compiler.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Clef
+  class Compiler
+    # @param score [Clef::Core::Score]
+    # @param style [Clef::Engraving::Style]
+    # @param plugins [Clef::Plugins::Registry]
+    def initialize(score, style: Clef::Engraving::Style.default, plugins: Clef.plugins)
+      @score = score
+      @style = style
+      @plugins = plugins
+    end
+
+    # @param path [String]
+    # @return [String]
+    def compile_to_pdf(path)
+      layout = build_layout
+      renderer = Clef::Renderer::PdfRenderer.new(style: @style)
+      @plugins.run_hook(:on_before_render, renderer)
+      renderer.render(@score, path, positions: layout[:positions])
+      path
+    end
+
+    # @param path [String]
+    # @return [String]
+    def compile_to_svg(path)
+      layout = build_layout
+      renderer = Clef::Renderer::SvgRenderer.new(style: @style)
+      @plugins.run_hook(:on_before_render, renderer)
+      renderer.render(@score, path, positions: layout[:positions])
+      path
+    end
+
+    private
+
+    def build_layout
+      @plugins.run_hook(:on_before_layout, @score)
+      timeline = Clef::Ir::MusicTree.build(@score)
+      spacing = Clef::Layout::Spacing.new(timeline, @style)
+      positions = spacing.compute
+      layout = { timeline: timeline, spacing: spacing, positions: positions }
+      @plugins.run_hook(:on_after_layout, layout)
+      layout
+    end
+  end
+end

data/lib/clef/core/chord.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    class Chord
+      attr_reader :pitches, :duration
+
+      # @param pitches [Array<Pitch>]
+      # @param duration [Duration]
+      def initialize(pitches, duration)
+        validate_pitches!(pitches)
+        raise ArgumentError, "duration must be a Clef::Core::Duration" unless duration.is_a?(Duration)
+
+        @pitches = pitches.sort
+        @duration = duration
+      end
+
+      # @return [Rational]
+      def length
+        duration.length
+      end
+
+      private
+
+      def validate_pitches!(pitches)
+        list = Array(pitches)
+        raise ArgumentError, "pitches must not be empty" if list.empty?
+        return if list.all? { |pitch| pitch.is_a?(Pitch) }
+
+        raise ArgumentError, "all chord pitches must be Clef::Core::Pitch"
+      end
+    end
+  end
+end

data/lib/clef/core/clef.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    class Clef
+      TYPES = %i[treble bass alto tenor soprano mezzo_soprano baritone percussion tab].freeze
+      REFERENCE = {
+        treble: [[:b, 4], 2],
+        bass: [[:d, 3], 2],
+        alto: [[:c, 4], 2],
+        tenor: [[:a, 3], 2],
+        soprano: [[:g, 4], 2],
+        mezzo_soprano: [[:e, 4], 2],
+        baritone: [[:f, 3], 2],
+        percussion: [[:b, 4], 2],
+        tab: [[:b, 4], 2]
+      }.freeze
+
+      attr_reader :type
+
+      # @param type [Symbol]
+      def initialize(type)
+        raise ArgumentError, "unsupported clef type: #{type}" unless TYPES.include?(type)
+
+        @type = type
+      end
+
+      # @return [Pitch]
+      def reference_pitch
+        note_name, octave = REFERENCE.fetch(type).first
+        Pitch.new(note_name, octave)
+      end
+
+      # @return [Integer]
+      def reference_line
+        REFERENCE.fetch(type).last
+      end
+    end
+  end
+end

data/lib/clef/core/duration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    class Duration
+      include Comparable
+
+      BASE_VALUES = {
+        whole: Rational(1, 1),
+        half: Rational(1, 2),
+        quarter: Rational(1, 4),
+        eighth: Rational(1, 8),
+        sixteenth: Rational(1, 16),
+        thirty_second: Rational(1, 32),
+        sixty_fourth: Rational(1, 64)
+      }.freeze
+      NUMBER_TO_BASE = {
+        1 => :whole,
+        2 => :half,
+        4 => :quarter,
+        8 => :eighth,
+        16 => :sixteenth,
+        32 => :thirty_second,
+        64 => :sixty_fourth
+      }.freeze
+      BASE_TO_NUMBER = NUMBER_TO_BASE.invert.freeze
+
+      attr_reader :base, :dots
+
+      # @param base [Symbol]
+      # @param dots [Integer]
+      def initialize(base, dots: 0)
+        validate_base!(base)
+        validate_dots!(dots)
+
+        @base = base
+        @dots = dots
+        freeze
+      end
+
+      # @return [Rational]
+      def base_value
+        BASE_VALUES.fetch(base)
+      end
+
+      # @return [Rational]
+      def length
+        base_value * (Rational(2, 1) - Rational(1, 2**dots))
+      end
+
+      # @param other [Duration]
+      # @return [Integer, nil]
+      def <=>(other)
+        return nil unless other.is_a?(self.class)
+
+        length <=> other.length
+      end
+
+      # @return [String]
+      def to_lilypond
+        "#{BASE_TO_NUMBER.fetch(base)}#{'.' * dots}"
+      end
+
+      # @param number [Integer]
+      # @param dots [Integer]
+      # @return [Duration]
+      def self.from_lilypond(number, dots = 0)
+        new(NUMBER_TO_BASE.fetch(number), dots: dots)
+      rescue KeyError
+        raise ArgumentError, "unsupported lilypond duration: #{number}"
+      end
+
+      class << self
+        BASE_VALUES.keys.each do |duration_name|
+          define_method(duration_name) do
+            new(duration_name)
+          end
+        end
+      end
+
+      private
+
+      def validate_base!(base)
+        return if BASE_VALUES.key?(base)
+
+        raise ArgumentError, "unknown duration base: #{base.inspect}"
+      end
+
+      def validate_dots!(dots)
+        return if dots.is_a?(Integer) && (0..3).cover?(dots)
+
+        raise ArgumentError, "dots must be an Integer between 0 and 3"
+      end
+    end
+  end
+end

data/lib/clef/core/key_signature.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    class KeySignature
+      MAJOR_ACCIDENTALS = {
+        c: { count: 0, type: :natural },
+        g: { count: 1, type: :sharp },
+        d: { count: 2, type: :sharp },
+        a: { count: 3, type: :sharp },
+        e: { count: 4, type: :sharp },
+        b: { count: 5, type: :sharp },
+        fis: { count: 6, type: :sharp },
+        cis: { count: 7, type: :sharp },
+        f: { count: 1, type: :flat },
+        bes: { count: 2, type: :flat },
+        ees: { count: 3, type: :flat },
+        aes: { count: 4, type: :flat },
+        des: { count: 5, type: :flat },
+        ges: { count: 6, type: :flat },
+        ces: { count: 7, type: :flat }
+      }.freeze
+      MINOR_ACCIDENTALS = {
+        a: { count: 0, type: :natural },
+        e: { count: 1, type: :sharp },
+        b: { count: 2, type: :sharp },
+        fis: { count: 3, type: :sharp },
+        cis: { count: 4, type: :sharp },
+        gis: { count: 5, type: :sharp },
+        dis: { count: 6, type: :sharp },
+        ais: { count: 7, type: :sharp },
+        d: { count: 1, type: :flat },
+        g: { count: 2, type: :flat },
+        c: { count: 3, type: :flat },
+        f: { count: 4, type: :flat },
+        bes: { count: 5, type: :flat },
+        ees: { count: 6, type: :flat },
+        aes: { count: 7, type: :flat }
+      }.freeze
+
+      attr_reader :tonic, :mode
+
+      # @param tonic [Pitch, Symbol]
+      # @param mode [Symbol]
+      def initialize(tonic, mode = :major)
+        @tonic = normalize_tonic(tonic)
+        validate_mode!(mode)
+        @mode = mode
+      end
+
+      # @return [Hash]
+      def accidentals
+        table = mode == :major ? MAJOR_ACCIDENTALS : MINOR_ACCIDENTALS
+        table.fetch(tonic_key) { { count: 0, type: :natural } }
+      end
+
+      private
+
+      def normalize_tonic(tonic)
+        return tonic if tonic.is_a?(Pitch)
+        return Pitch.new(tonic, 4) if tonic.is_a?(Symbol)
+
+        raise ArgumentError, "tonic must be a Pitch or Symbol"
+      end
+
+      def tonic_key
+        base = tonic.note_name.to_s
+        suffix = tonic.alteration.positive? ? "is" * tonic.alteration : "es" * tonic.alteration.abs
+        "#{base}#{suffix}".to_sym
+      end
+
+      def validate_mode!(mode)
+        return if %i[major minor].include?(mode)
+
+        raise ArgumentError, "mode must be :major or :minor"
+      end
+    end
+  end
+end

data/lib/clef/core/measure.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    class Measure
+      attr_reader :number, :voices
+      attr_accessor :key_signature, :time_signature, :clef
+
+      # @param number [Integer]
+      # @param time_signature [TimeSignature, nil]
+      def initialize(number, time_signature: nil)
+        raise ArgumentError, "measure number must be positive" unless number.is_a?(Integer) && number.positive?
+
+        @number = number
+        @time_signature = time_signature
+        @voices = {}
+      end
+
+      # @param id [Symbol]
+      # @yield [Voice]
+      # @return [Voice]
+      def voice(id = :default)
+        current = voices[id] ||= Voice.new(id: id)
+        yield(current) if block_given?
+        warn_overflow_if_needed(id, current)
+        current
+      end
+
+      # @return [Array<Symbol>]
+      def overflowing_voice_ids
+        return [] unless time_signature
+
+        voices.filter_map { |id, voice| id if voice.total_length > time_signature.measure_length }
+      end
+
+      private
+
+      def warn_overflow_if_needed(id, voice)
+        return unless time_signature
+        return unless voice.total_length > time_signature.measure_length
+
+        warn("Measure #{number} voice #{id} exceeds time signature length")
+      end
+    end
+  end
+end

data/lib/clef/core/note.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    class Note
+      attr_reader :pitch, :duration
+      attr_accessor :articulations, :tied
+
+      # @param pitch [Pitch]
+      # @param duration [Duration]
+      # @param articulations [Array<Symbol>]
+      # @param tied [Boolean]
+      def initialize(pitch, duration, articulations: [], tied: false)
+        validate_pitch!(pitch)
+        validate_duration!(duration)
+
+        @pitch = pitch
+        @duration = duration
+        @articulations = Array(articulations).map(&:to_sym)
+        @tied = !!tied
+      end
+
+      # @return [Rational]
+      def length
+        duration.length
+      end
+
+      private
+
+      def validate_pitch!(pitch)
+        return if pitch.is_a?(Pitch)
+
+        raise ArgumentError, "pitch must be a Clef::Core::Pitch"
+      end
+
+      def validate_duration!(duration)
+        return if duration.is_a?(Duration)
+
+        raise ArgumentError, "duration must be a Clef::Core::Duration"
+      end
+    end
+  end
+end