badline 0.1.0 → 0.2.0

data/lib/badline/audio/jukebox.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # Plays a tune's songs interactively: the console's keys step between
+    # songs, pause and quit, and the status line follows along. It stops
+    # when a song ends, on q, or on Ctrl-C.
+    #
+    # `renderer` builds the renderer for a song at the sink's rate, and
+    # `length` gives a song's length in seconds.
+    class Jukebox
+      def initialize(sink, console, songs:, renderer:, length:)
+        @sink = sink
+        @console = console
+        @songs = songs
+        @renderer = renderer
+        @length = length
+        @below = false
+      end
+
+      # Returns the result of the last song's Playback#play.
+      def run(song)
+        loop do
+          @action = nil
+          result = play(song)
+          song = following(song)
+          return result unless song
+        end
+      end
+
+      private
+
+      def play(song)
+        @song = song
+        @elapsed = 0.0
+        @playback = Playback.new(@sink, sleeper: ->(seconds) { react(@console.wait(seconds)) },
+                                        on_underrun: -> { @below = true })
+        draw
+        @playback.play(@renderer.call(song, @sink.rate)) do |played|
+          @elapsed = played
+          react(@console.wait(0))
+          draw
+        end
+      end
+
+      def following(song)
+        case @action
+        when :next then song + 1
+        when :previous then song - 1
+        end
+      end
+
+      def react(actions)
+        actions.each do |action|
+          case action
+          when :pause then toggle_pause
+          when :next then skip(:next) if @song < @songs
+          when :previous then skip(:previous) if @song > 1
+          when :quit then skip(:quit)
+          end
+        end
+      end
+
+      def skip(action)
+        @action = action
+        @playback.stop
+      end
+
+      def toggle_pause
+        @playback.paused? ? @playback.resume : @playback.pause
+        draw
+      end
+
+      def draw
+        notes = []
+        notes << "paused" if @playback.paused?
+        notes << "below real time" if @below
+        @console.status(song: @song, songs: @songs, elapsed: @elapsed, length: @length.call(@song), notes:)
+      end
+    end
+  end
+end

data/lib/badline/audio/machine_player.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # Runs a tune on the whole machine, for the RSID tunes that install their
+    # own interrupts and expect a booted C64 underneath. The tune goes in
+    # through the same stub `Media` uses and BASIC SYSes it; rendering starts
+    # when the CPU reaches that stub.
+    class MachinePlayer
+      FRAME_CYCLES = BarePlayer::FRAME_CYCLES
+
+      # Boot, plus room for the keyboard buffer to type the SYS.
+      START_LIMIT = 15_000_000
+
+      def initialize(tune, song: nil, sid_model: tune.sid_model)
+        @tune = tune
+        @song = song || tune.start_song
+        @computer = Computer.new(sid_model:)
+        @injected = false
+        @started = false
+      end
+
+      def start
+        @computer.on_init { inject }
+        @computer.cpu.install_trap(@tune.driver_address) { begin_playing }
+        @computer.cycle! until @started || @computer.cycles > START_LIMIT
+      end
+
+      def sid = @computer.sid
+
+      # Advances one PAL frame, or `budget` cycles if that is shorter, then
+      # yields whatever the SID recorded over it. Returns the cycles advanced.
+      def frame(budget, &)
+        cycles = [budget, FRAME_CYCLES].min
+        cycles.times { @computer.cycle! }
+        sid.drain_samples.each(&)
+        cycles
+      end
+
+      private
+
+      def inject
+        @computer.ram.write(@tune.load_address, @tune.data)
+        @computer.ram.write(@tune.driver_address, @tune.driver(song: @song))
+        @computer.type_text("sys#{@tune.driver_address}\r")
+        @injected = true
+      end
+
+      def begin_playing
+        return unless @injected
+
+        @computer.sid.synthesize!
+        @started = true
+      end
+    end
+  end
+end

data/lib/badline/audio/options.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Badline
+  module Audio
+    # The command line of `badline-sid`. It loads nothing else from badline,
+    # so the executable can parse and reject its arguments before paying for
+    # the emulator.
+    class Options
+      class Error < StandardError; end
+
+      FALLBACK_SECONDS = 60.0
+
+      DEFAULT_RATE = 44_100
+
+      SID_MODELS = { "6581" => :mos6581, "8580" => :mos8580 }.freeze
+
+      BANNER = <<~BANNER.freeze
+        Usage: badline-sid [options] tune.sid [-o output]
+
+        Plays a .sid tune on the host's audio device, or with an output file
+        renders it to 16-bit PCM instead. The container follows the output
+        file's extension, .wav or .aiff.
+
+        A .sid file carries no length of its own. Without --seconds the tune is
+        looked up by MD5 in HVSC's Songlengths.md5, taken from --songlengths, from
+        the DOCUMENTS directory of an HVSC collection above the tune, or from
+        $HVSC_BASE. Failing all of those it runs for #{FALLBACK_SECONDS.to_i} seconds.
+
+        Played on a terminal, n or → skips to the next song, p or ← to the
+        previous one, space pauses and q quits.
+
+        PSID tunes run on a bare CPU and SID, faster than real time. RSID
+        tunes boot the whole machine and run at about half real time, so
+        they stutter when played. --filter-chunk 1 runs the filter cycle by
+        cycle, which is exact but takes about twice as long.
+
+        Options:
+      BANNER
+
+      attr_reader :tune_path, :output, :song, :seconds, :songlengths, :sid_model, :filter_chunk
+
+      def self.parse(argv) = new.parse(argv)
+
+      def initialize
+        @jit = true
+        @quiet = false
+        @tui = true
+        @help = false
+      end
+
+      def parse(argv)
+        arguments = parser.parse(argv)
+        @tune_path, positional_output, *extra = arguments
+        raise Error, "unexpected argument: #{extra.first}" if extra.any?
+
+        @output ||= positional_output
+        validate unless help?
+        self
+      rescue OptionParser::ParseError => e
+        raise Error, e.message
+      end
+
+      def render? = !output.nil?
+
+      def rate = @rate || DEFAULT_RATE
+
+      def rate_given? = !@rate.nil?
+
+      def help = parser.help
+
+      def help? = @help
+
+      def quiet? = @quiet
+
+      def tui? = @tui
+
+      def jit? = @jit
+
+      private
+
+      def validate
+        raise Error, "no tune given" unless tune_path
+
+        validate_numbers
+        validate_paths
+      end
+
+      def validate_numbers
+        raise Error, "invalid argument: --song #{song}" if song&.< 1
+        raise Error, "invalid argument: --seconds #{seconds}" unless seconds.nil? || seconds.positive?
+        raise Error, "invalid argument: --rate #{rate}" unless rate.positive?
+        raise Error, "invalid argument: --filter-chunk #{filter_chunk}" if filter_chunk&.< 1
+      end
+
+      def validate_paths
+        [tune_path, songlengths].compact.each do |path|
+          raise Error, "no such file: #{path}" unless File.exist?(path)
+        end
+      end
+
+      def parser
+        @parser ||= OptionParser.new do |opts|
+          opts.banner = BANNER
+          define_tune_options(opts)
+          define_output_options(opts)
+          define_run_options(opts)
+        end
+      end
+
+      def define_tune_options(opts)
+        opts.on("-s", "--song N", Integer, "Subtune to play, from 1 (default: the tune's own)") { |n| @song = n }
+        opts.on("--seconds N", Float, "Length to play (default: the tune's own)") { |n| @seconds = n }
+        opts.on("--songlengths PATH", "HVSC Songlengths.md5 to take the length from") { |path| @songlengths = path }
+        opts.on("--sid MODEL", SID_MODELS,
+                "SID to play on: 6581 or 8580 (default: the tune's own, else 6581)") { |model| @sid_model = model }
+      end
+
+      def define_output_options(opts)
+        opts.on("-o", "--output PATH", "Render to a .wav or .aiff file instead of playing") { |path| @output = path }
+        opts.on("--rate HZ", Integer,
+                "Sample rate (default: #{DEFAULT_RATE}, or the audio device's own)") { |n| @rate = n }
+        opts.on("--filter-chunk N", Integer, "Filter step in cycles, 1 is exact (default: 4)") do |n|
+          @filter_chunk = n
+        end
+      end
+
+      def define_run_options(opts)
+        opts.on("--quiet", "Don't report progress") { @quiet = true }
+        opts.on("--no-tui", "Play without the interactive display, even on a terminal") { @tui = false }
+        opts.on("--disable-jit", "Run without enabling YJIT") { @jit = false }
+        opts.on("-h", "--help", "Show this help") { @help = true }
+      end
+    end
+  end
+end

data/lib/badline/audio/pcm_writer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # Streams mono signed 16-bit samples into a container, buffering them and
+    # patching the header's length fields once the stream ends.
+    class PCMWriter
+      BUFFER = 4096
+
+      attr_reader :rate, :samples
+
+      def self.open(path, rate:)
+        File.open(path, "wb") do |io|
+          writer = new(io, rate:)
+          yield writer
+          writer.finish
+        end
+      end
+
+      def initialize(io, rate:)
+        @io = io
+        @rate = rate
+        @samples = 0
+        @buffer = []
+        @io.write(header)
+      end
+
+      def <<(sample)
+        @buffer << sample
+        flush if @buffer.length >= BUFFER
+        self
+      end
+
+      def finish
+        flush
+        patch
+      end
+
+      private
+
+      def flush
+        return if @buffer.empty?
+
+        @io.write(@buffer.pack(pack_format))
+        @samples += @buffer.length
+        @buffer.clear
+      end
+
+      def data_size = @samples * 2
+
+      def write_at(offset, bytes)
+        @io.seek(offset)
+        @io.write(bytes)
+      end
+    end
+  end
+end

data/lib/badline/audio/playback.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # Plays a renderer's frames through a sink in real time. The queue is
+    # kept a little ahead of the device: a frame is only rendered once the
+    # queue has drained below `ahead` seconds, and the device only starts
+    # once the queue first reaches it.
+    #
+    # A sink answers #rate, #queue(samples), #queued_seconds, #start, #pause
+    # and #clear; whoever opened it closes it. An emulator running below
+    # real time lets the queue run dry and the audio stutters; `on_underrun`
+    # hears about the first time.
+    class Playback
+      AHEAD = 0.15
+
+      def initialize(sink, ahead: AHEAD, sleeper: ->(seconds) { sleep(seconds) }, on_underrun: nil)
+        @sink = sink
+        @ahead = ahead
+        @sleeper = sleeper
+        @on_underrun = on_underrun
+        @started = false
+        @stopped = false
+        @paused = false
+        @underrun = false
+      end
+
+      def stopped? = @stopped
+
+      def paused? = @paused
+
+      def underrun? = @underrun
+
+      # Stops at the end of the next wait; the queue is dropped rather than
+      # played out.
+      def stop = @stopped = true
+
+      # Holds the device where it is. Rendering stalls too, since the queue
+      # stops draining.
+      def pause
+        @paused = true
+        @sink.pause if @started
+      end
+
+      def resume
+        @paused = false
+        @sink.start if @started
+      end
+
+      # Plays to the end of the renderer and waits for the device to finish,
+      # yielding the seconds played so far after each frame. Returns
+      # :finished, :stopped, or :interrupted after a Ctrl-C.
+      def play(renderer)
+        @sink.pause
+        renderer.stream do |samples, rendered|
+          break if @stopped
+
+          enqueue(samples)
+          yield [rendered - @sink.queued_seconds, 0.0].max if block_given?
+        end
+        drain
+        @stopped ? :stopped : :finished
+      rescue Interrupt
+        @stopped = true
+        :interrupted
+      ensure
+        @sink.clear if @stopped
+      end
+
+      private
+
+      def enqueue(samples)
+        wait_below(@ahead)
+        underrun! if @started && @sink.queued_seconds.zero?
+        @sink.queue(samples)
+        start if @sink.queued_seconds >= @ahead
+      end
+
+      def drain
+        start
+        wait_below(1.fdiv(@sink.rate))
+      end
+
+      def start
+        return if @started
+
+        @started = true
+        @sink.start unless @paused
+      end
+
+      def underrun!
+        return if @underrun
+
+        @underrun = true
+        @on_underrun&.call
+      end
+
+      def wait_below(level)
+        until @stopped
+          excess = @sink.queued_seconds - level
+          break if excess.negative?
+
+          @sleeper.call([excess, 0.001].max)
+        end
+      end
+    end
+  end
+end

data/lib/badline/audio/renderer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # Renders a .sid tune to a PCM file, or streams its samples to whoever
+    # plays them. A PSID tune with a play address runs on the bare rig;
+    # anything else drives its own interrupts and needs the whole machine.
+    #
+    # A .sid file carries no length, so the caller says how many seconds to
+    # render.
+    class Renderer
+      class UnknownFormatError < StandardError; end
+
+      DEFAULT_RATE = 44_100
+
+      CONTAINERS = { ".wav" => WAV, ".aiff" => AIFF, ".aif" => AIFF }.freeze
+
+      # The cycles the SID's filter integrates at a time; 1 renders the
+      # filter cycle by cycle, exactly.
+      attr_writer :filter_chunk
+
+      def initialize(tune, seconds:, song: nil, rate: DEFAULT_RATE, sid_model: tune.sid_model)
+        @tune = tune
+        @seconds = seconds
+        @song = song
+        @rate = rate
+        @sid_model = sid_model
+        @filter_chunk = SID::FILTER_CHUNK
+      end
+
+      def player
+        @player ||= (bare? ? BarePlayer : MachinePlayer).new(@tune, song: @song, sid_model: @sid_model)
+      end
+
+      # Yields the seconds rendered so far after every frame.
+      def render(path)
+        container = container_for(path)
+        player.start
+        container.open(path, rate: @rate) do |writer|
+          each_frame do |samples, seconds|
+            samples.each { |sample| writer << sample }
+            yield seconds if block_given?
+          end
+        end
+      end
+
+      # Starts the tune, then yields each frame's samples along with the
+      # seconds rendered so far.
+      def stream(&)
+        player.start
+        each_frame(&)
+      end
+
+      private
+
+      def bare? = @tune.format == "PSID" && @tune.play_address.positive?
+
+      def total_samples = (@seconds * @rate).round
+
+      # The cycles it takes to close exactly `total_samples` windows; the SID
+      # records floor(cycles * rate / clock) of them.
+      def total_cycles
+        ((total_samples * TimeOfDay::CLOCK_HZ) + @rate - 1) / @rate
+      end
+
+      def container_for(path)
+        extension = File.extname(path).downcase
+        CONTAINERS.fetch(extension) do
+          raise UnknownFormatError, "Unknown output format: #{extension}"
+        end
+      end
+
+      def each_frame
+        player.sid.record(rate: @rate, filter_chunk: @filter_chunk)
+        total = total_cycles
+        remaining = total
+        while remaining.positive?
+          samples = []
+          remaining -= player.frame(remaining) { |sample| samples << sample }
+          yield samples, (total - remaining).fdiv(TimeOfDay::CLOCK_HZ)
+        end
+      end
+    end
+  end
+end

data/lib/badline/audio/sdl_sink.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # The host's audio device, fed through SDL's queue: mono signed 16-bit
+    # samples go in at the device's rate and SDL plays them out behind us.
+    #
+    # ruby-sdl2 only wraps SDL_mixer, which can't stream raw samples, so the
+    # queue API is called through Fiddle on the libSDL2 the extension has
+    # already loaded.
+    class SDLSink
+      class Error < StandardError; end
+
+      INIT_AUDIO = 0x10
+
+      AUDIO_S16SYS = [1].pack("s").getbyte(0) == 1 ? 0x8010 : 0x9010
+
+      ALLOW_FREQUENCY_CHANGE = 0x01
+
+      # int freq; Uint16 format; Uint8 channels, silence; Uint16 samples,
+      # padding; Uint32 size; then the callback and userdata pointers.
+      SPEC_LAYOUT = "lSCCSSLQQ"
+
+      FUNCTIONS = {
+        SDL_InitSubSystem: [%i[uint32], :int],
+        SDL_QuitSubSystem: [%i[uint32], :void],
+        SDL_GetError: [[], :string],
+        SDL_OpenAudioDevice: [%i[pointer int pointer pointer int], :uint32],
+        SDL_CloseAudioDevice: [%i[uint32], :void],
+        SDL_PauseAudioDevice: [%i[uint32 int], :void],
+        SDL_QueueAudio: [%i[uint32 pointer uint32], :int],
+        SDL_GetQueuedAudioSize: [%i[uint32], :uint32],
+        SDL_ClearQueuedAudio: [%i[uint32], :void]
+      }.freeze
+
+      attr_reader :rate
+
+      # With `exact_rate` false SDL may pick the device's own rate instead,
+      # which #rate then reports.
+      def initialize(rate:, exact_rate: false, buffer: 1024)
+        load_sdl
+        check(sdl(:SDL_InitSubSystem, INIT_AUDIO))
+        @device = open_device(rate, exact_rate ? 0 : ALLOW_FREQUENCY_CHANGE, buffer)
+      end
+
+      def queue(samples)
+        data = samples.pack("s*")
+        check(sdl(:SDL_QueueAudio, @device, data, data.bytesize))
+      end
+
+      def queued_seconds = sdl(:SDL_GetQueuedAudioSize, @device).fdiv(2 * rate)
+
+      def start = sdl(:SDL_PauseAudioDevice, @device, 0)
+
+      def pause = sdl(:SDL_PauseAudioDevice, @device, 1)
+
+      def clear = sdl(:SDL_ClearQueuedAudio, @device)
+
+      def close
+        return unless @device
+
+        sdl(:SDL_CloseAudioDevice, @device)
+        sdl(:SDL_QuitSubSystem, INIT_AUDIO)
+        @device = nil
+      end
+
+      private
+
+      def open_device(rate, allowed_changes, buffer)
+        wanted = [rate, AUDIO_S16SYS, 1, 0, buffer, 0, 0, 0, 0].pack(SPEC_LAYOUT)
+        obtained = "\0".b * 32
+        device = sdl(:SDL_OpenAudioDevice, nil, 0, wanted, obtained, allowed_changes)
+        raise Error, sdl(:SDL_GetError) if device.zero?
+
+        @rate = obtained.unpack1("l")
+        device
+      end
+
+      def check(result)
+        raise Error, sdl(:SDL_GetError) if result.negative?
+
+        result
+      end
+
+      def sdl(name, *) = @functions.fetch(name).call(*)
+
+      def load_sdl
+        require "fiddle"
+        require "sdl2"
+        @functions = FUNCTIONS.to_h do |name, (arguments, result)|
+          [name, Fiddle::Function.new(Fiddle::Handle::DEFAULT[name.to_s],
+                                      arguments.map { |type| fiddle_type(type) }, fiddle_type(result))]
+        end
+      end
+
+      def fiddle_type(type)
+        { uint32: Fiddle::TYPE_UINT32_T, int: Fiddle::TYPE_INT, void: Fiddle::TYPE_VOID,
+          pointer: Fiddle::TYPE_VOIDP, string: Fiddle::TYPE_CONST_STRING }.fetch(type)
+      end
+    end
+  end
+end

data/lib/badline/audio/wav.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # RIFF/WAVE, little-endian throughout.
+    class WAV < PCMWriter
+      private
+
+      def pack_format = "s<*"
+
+      def header
+        ["RIFF", 0, "WAVE",
+         "fmt ", 16, 1, 1, rate, rate * 2, 2, 16,
+         "data", 0].pack("a4Va4a4VvvVVvva4V")
+      end
+
+      def patch
+        write_at(4, [36 + data_size].pack("V"))
+        write_at(40, [data_size].pack("V"))
+      end
+    end
+  end
+end

data/lib/badline/audio.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "badline/audio/options"
+require "badline/audio/pcm_writer"
+require "badline/audio/wav"
+require "badline/audio/aiff"
+require "badline/audio/bare_player"
+require "badline/audio/machine_player"
+require "badline/audio/renderer"
+require "badline/audio/sdl_sink"
+require "badline/audio/playback"
+require "badline/audio/console"
+require "badline/audio/jukebox"
+require "badline/audio/cli"