badline 0.6.0 → 0.7.0

data/lib/badline/audio/jukebox.rb

@@ -2,53 +2,98 @@
 
 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. A song that
-    # plays to its end moves on to the next one. It stops after the last
-    # song, on q, or on Ctrl-C.
+    # Plays a Media::Queue of tunes interactively: the console's keys step
+    # between tunes and between a tune's subtunes, seek within the subtune, pause,
+    # turn the queue's shuffle, loop and all-subtunes modes on and off, and
+    # quit, and the status line follows along. Seeking runs the subtune
+    # silently up to where it was asked to go: on from where it is to go
+    # forward, and from the start again to go back. A subtune that plays to
+    # its end moves on as Media::Queue#advance says. It stops at the end of
+    # the queue, 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.
+    # `renderer` builds the renderer for an entry's subtune at the sink's
+    # rate, or returns nil for an entry that can't play, which is skipped
+    # in the direction the queue was stepping. `length` gives an entry's
+    # subtune's length in seconds.
     class Jukebox
-      def initialize(sink, console, songs:, renderer:, length:)
+      SEEK_STEP = 10.0
+
+      # How long a wait on an empty queue lasts before it checks again.
+      IDLE = 0.05
+
+      # How long the status line says the player fell below real time after
+      # the last time it did.
+      BELOW_NOTE = 3.0
+
+      def initialize(sink, console, queue:, renderer:, length:)
         @sink = sink
         @console = console
-        @songs = songs
+        @queue = queue
         @renderer = renderer
         @length = length
-        @below = false
+        @backward = false
+        @below_at = -BELOW_NOTE
+        @from = 0.0
       end
 
-      # Returns the result of the last song's Playback#play.
-      def run(song)
+      # Returns the result of the last subtune's Playback#play, or :unplayable
+      # when the last entry reached couldn't play.
+      def run
+        skipped = 0
         loop do
-          @action = nil
-          result = play(song)
-          song = following(song, result)
-          return result unless song
+          return :stopped unless tunes_to_play?
+
+          @moved = false
+          @quit = false
+          result = play(@queue.entry, @queue.part)
+          return result if @quit
+          next if @moved
+
+          skipped = result == :unplayable ? skipped + 1 : 0
+          return result if skipped >= @queue.size || !move_on(result)
         end
       end
 
       private
 
-      def play(song)
-        @song = song
+      # Waits on the console while the queue is empty, as a window's is
+      # until files are dropped on it. Returns false when asked to quit.
+      def tunes_to_play?
+        while @queue.empty?
+          actions = @console.wait(IDLE)
+          return false if actions.include?(:quit)
+
+          @queue.add(@console.dropped) if actions.include?(:drop)
+        end
+        true
+      end
+
+      def move_on(result)
+        return @queue.advance if result == :finished
+        return false unless result == :unplayable
+        return @queue.advance unless @backward
+
+        @queue.previous_entry || @queue.advance
+      end
+
+      def play(entry, subtune)
+        @entry = entry
+        @subtune = subtune
         @elapsed = 0.0
+        renderer = @renderer.call(entry, subtune, @sink.rate)
+        return :unplayable if renderer.nil?
+
+        renderer.from = @from
+        @streaming = renderer
+        @from = 0.0
+        @backward = false
         @playback = Playback.new(@sink, sleeper: ->(seconds) { react(@console.wait(seconds)) },
-                                        on_underrun: -> { @below = true })
+                                        on_underrun: -> { @below_at = now })
         draw
-        @playback.play(@renderer.call(song, @sink.rate)) do |played|
+        @playback.play(renderer) do |played|
           @elapsed = played
           react(@console.wait(0))
-          draw
-        end
-      end
-
-      def following(song, result)
-        case @action
-        when :next then song + 1
-        when :previous then song - 1
-        else song + 1 if result == :finished && song < @songs
+          draw unless @moved
         end
       end
 
@@ -56,29 +101,69 @@ module Badline
         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)
+          when :shuffle then @queue.toggle_shuffle
+          when :loop then @queue.toggle_loop
+          when :all_subtunes then @queue.toggle_all_parts
+          when :quit then quit
+          when :drop then @queue.add(@console.dropped)
+          when :seek then seek(@console.seek_to)
+          when :forward then seek(@elapsed + SEEK_STEP)
+          when :back then seek(@elapsed - SEEK_STEP)
+          else skip if step(action)
           end
         end
+        draw unless actions.empty? || @moved
+      end
+
+      def step(action)
+        @backward = action == :previous if %i[next previous].include?(action)
+        case action
+        when :next then @queue.next_entry
+        when :previous then @queue.previous_entry
+        when :next_subtune then @queue.next_part
+        when :previous_subtune then @queue.previous_part
+        end
+      end
+
+      def seek(seconds)
+        target = seconds.clamp(0.0, [@length.call(@entry, @subtune) - 1.0, 0.0].max)
+        return @streaming.from = target if target > @elapsed
+
+        @from = target
+        skip
       end
 
-      def skip(action)
-        @action = action
+      def skip
+        @moved = true
+        @playback.stop
+      end
+
+      def quit
+        @quit = true
         @playback.stop
       end
 
       def toggle_pause
         @playback.paused? ? @playback.resume : @playback.pause
-        draw
       end
 
       def draw
+        @console.place(@queue.position, @queue.size)
+        @console.status(subtune: @subtune, subtunes: @entry.parts, elapsed: @elapsed,
+                        length: @length.call(@entry, @subtune), notes:)
+      end
+
+      def notes
         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:)
+        notes << "shuffle" if @queue.shuffle?
+        notes << "loop" if @queue.loop?
+        notes << "all subtunes" if @queue.all_parts?
+        notes << "below real time" if now - @below_at < BELOW_NOTE
+        notes
       end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
   end
 end

data/lib/badline/audio/machine_player.rb

@@ -14,10 +14,13 @@ module Badline
       # 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)
+      def initialize(tune, subtune: nil, sid_models: tune.sid_models)
         @tune = tune
-        @song = song || tune.start_song
-        @computer = Computer.new(sid_model:)
+        @subtune = subtune || tune.start_subtune
+        @computer = Computer.new(sid_model: sid_models[0])
+        @stereo = Stereo.new(@computer.address_bus, tune, sid_models)
+        @extras = @stereo.extras
+        @multi = !@extras.empty?
         region = @computer.region
         @frame_cycles = region.cycles_per_line * region.lines_per_frame
         @injected = false
@@ -27,28 +30,40 @@ module Badline
       def start
         @computer.on_init { inject }
         @computer.cpu.install_trap(@tune.entry_address) { begin_playing }
-        @computer.cycle! until @started || @computer.cycles > START_LIMIT
+        step until @started || @computer.cycles > START_LIMIT
       end
 
+      attr_reader :stereo
+
       def sid = @computer.sid
 
       def clock_hz = @computer.region.clock_hz
 
       # Advances one frame of the machine, or `budget` cycles if that is
-      # shorter, then yields whatever the SID recorded over it. Returns the
-      # cycles advanced.
+      # shorter, then yields whatever the SIDs recorded over it, in stereo.
+      # Returns the cycles advanced.
       def frame(budget, &)
         cycles = [budget, @frame_cycles].min
-        cycles.times { @computer.cycle! }
-        sid.drain_samples.each(&)
+        if @multi
+          cycles.times { step }
+        else
+          cycles.times { @computer.cycle! }
+        end
+        @stereo.mix(&)
         cycles
       end
 
       private
 
+      # The extra SIDs clock ahead of the CPU, as the machine's own does.
+      def step
+        @extras.each(&:cycle!) if @multi
+        @computer.cycle!
+      end
+
       def inject
         @computer.ram.write(@tune.load_address, @tune.data)
-        @tune.boot_memory(song: @song).each { |address, bytes| @computer.ram.write(address, bytes) }
+        @tune.boot_memory(subtune: @subtune).each { |address, bytes| @computer.ram.write(address, bytes) }
         @computer.type_text(@tune.boot_command)
         @injected = true
       end
@@ -56,7 +71,7 @@ module Badline
       def begin_playing
         return if @started || !@injected
 
-        @computer.sid.synthesize!
+        @stereo.synthesize!
         @started = true
       end
     end

data/lib/badline/audio/pcm_writer.rb

@@ -2,24 +2,26 @@
 
 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.
+    # Streams signed 16-bit samples into a container, buffering them and
+    # patching the header's length fields once the stream ends. With more
+    # than one channel the samples come interleaved, a frame at a time.
     class PCMWriter
       BUFFER = 4096
 
-      attr_reader :rate, :samples
+      attr_reader :rate, :channels, :samples
 
-      def self.open(path, rate:)
+      def self.open(path, rate:, channels: 1)
         File.open(path, "wb") do |io|
-          writer = new(io, rate:)
+          writer = new(io, rate:, channels:)
           yield writer
           writer.finish
         end
       end
 
-      def initialize(io, rate:)
+      def initialize(io, rate:, channels: 1)
         @io = io
         @rate = rate
+        @channels = channels
         @samples = 0
         @buffer = []
         @io.write(header)
@@ -48,6 +50,8 @@ module Badline
 
       def data_size = @samples * 2
 
+      def frames = @samples / @channels
+
       def write_at(offset, bytes)
         @io.seek(offset)
         @io.write(bytes)

data/lib/badline/audio/playback.rb

@@ -7,10 +7,11 @@ module Badline
     # 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
+    # A sink answers #rate, #queue(samples), which takes stereo samples
+    # interleaved, #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.
+    # hears of each time it does.
     class Playback
       # What a sink raises when the audio device won't open.
       class DeviceError < StandardError; end
@@ -73,6 +74,8 @@ module Badline
       private
 
       def enqueue(samples)
+        return if samples.empty?
+
         wait_below(@ahead)
         underrun! if @started && @sink.queued_seconds.zero?
         @sink.queue(samples)
@@ -92,8 +95,6 @@ module Badline
       end
 
       def underrun!
-        return if @underrun
-
         @underrun = true
         @on_underrun&.call
       end

data/lib/badline/audio/queued_tune.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # A .sid tune in the player's Media::Queue, read only once the queue or
+    # the player first asks about it, so a queue of a whole collection
+    # starts at once. Its subtunes, SID model and lengths follow the options:
+    # --subtune picks the subtune to start on, --sid the model and --seconds the
+    # length, and without them the tune's own header and HVSC's database
+    # decide.
+    #
+    # A file that won't read as a tune, or lacks the subtune asked for, gets
+    # an #error and a single subtune.
+    class QueuedTune < Media::Queue::Entry
+      def initialize(path, options, subtune: nil)
+        super(path)
+        @options = options
+        @subtune = subtune
+        @tune = nil
+        @read = false
+        @error = ""
+        @lengths = nil
+        @lengths_read = false
+      end
+
+      def part
+        read
+        @part
+      end
+
+      def parts
+        read
+        @parts
+      end
+
+      # Why the tune can't play, or "" when it can.
+      def error
+        read
+        @error
+      end
+
+      def tune = @tune ||= Storage::SIDFile.new(path)
+
+      # Lets go of the tune's data, which #tune reads again if asked.
+      def release = @tune = nil
+
+      # Each SID's model, SID 1's first: the one --sid names for all of
+      # them, or each one's own.
+      def sid_models
+        forced = @options.sid_model
+        forced ? Array.new(tune.sids, forced) : tune.sid_models
+      end
+
+      def model_name = sid_models.map { |model| model.to_s.delete_prefix("mos") }.join(" + ")
+
+      def length(subtune) = @options.seconds || songlengths&.at(subtune - 1) || @options.fallback_seconds
+
+      # How long the subtune may stay silent before it ends, or nil when its
+      # length is known rather than the fallback.
+      def silence(subtune) = @options.seconds || songlengths&.at(subtune - 1) ? nil : @options.silence_seconds
+
+      # The header's name, author and release, those it fills in.
+      def header = [tune.name, tune.author, tune.released].reject(&:empty?)
+
+      private
+
+      def read
+        return if @read
+
+        @read = true
+        @parts = tune.subtunes
+        @part = @subtune || tune.start_subtune
+        @error = "no subtune #{@part}: the tune has #{@parts}" if @part > @parts
+      rescue Storage::SIDFile::FormatError => e
+        @error = e.message
+      end
+
+      # HVSC's database is keyed by the tune's MD5 and lists one length per
+      # subtune.
+      def songlengths
+        return @lengths if @lengths_read
+
+        @lengths_read = true
+        database = @options.songlengths || Storage::SongLengths.locate(path)
+        @lengths = database && Storage::SongLengths.new(database).lengths(tune.md5)
+      end
+    end
+  end
+end

data/lib/badline/audio/renderer.rb

@@ -3,40 +3,70 @@
 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.
+    # plays them, in stereo with the left and right interleaved (Stereo).
+    # 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.
+    # render. For a tune whose length is a guess, #silence= also ends it
+    # once the output has held still for that many seconds.
     class Renderer
       class UnknownFormatError < StandardError; end
 
       DEFAULT_RATE = 44_100
 
+      # How far a sample may stray from where the output settled and still
+      # count as silence. A 6581 settles at a DC offset rather than at zero.
+      QUIET = 16
+
       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)
+      # The seconds rendered so far, short of the length once the tune has
+      # fallen silent.
+      attr_reader :rendered, :tune, :rate
+
+      # Hears each frame's samples and the seconds rendered by its end, as
+      # they are rendered.
+      attr_writer :observer
+
+      # Where #stream starts: the frames before it are rendered as fast as
+      # they go and yielded without their samples, so the seconds rendered
+      # still count up to it. Set while streaming, it skips ahead from the
+      # frame rendered last.
+      attr_writer :from
+
+      def initialize(tune, seconds:, subtune: nil, rate: DEFAULT_RATE, sid_models: tune.sid_models)
         @tune = tune
         @seconds = seconds
-        @song = song
+        @subtune = subtune
         @rate = rate
-        @sid_model = sid_model
+        @sid_models = sid_models
         @filter_chunk = SID::FILTER_CHUNK
+        @silent_samples = 0
+        @level = 0
+        @still = 0
+        @rendered = 0.0
+        @observer = ->(_samples, _rendered) {}
+        @from = 0.0
+      end
+
+      def silence=(seconds)
+        @silent_samples = (seconds * @rate).round
       end
 
       def player
-        @player ||= (bare? ? BarePlayer : MachinePlayer).new(@tune, song: @song, sid_model: @sid_model)
+        @player ||= (bare? ? BarePlayer : MachinePlayer).new(@tune, subtune: @subtune, sid_models: @sid_models)
       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|
+        container.open(path, rate: @rate, channels: 2) do |writer|
           each_frame do |samples, seconds|
             samples.each { |sample| writer << sample }
             yield seconds if block_given?
@@ -71,14 +101,31 @@ module Badline
       end
 
       def each_frame
-        player.sid.record(rate: @rate, filter_chunk: @filter_chunk, clock_hz: player.clock_hz)
+        player.stereo.record(rate: @rate, filter_chunk: @filter_chunk, clock_hz: player.clock_hz)
         total = total_cycles
         remaining = total
         while remaining.positive?
           samples = []
           remaining -= player.frame(remaining) { |sample| samples << sample }
-          yield samples, (total - remaining).fdiv(player.clock_hz)
+          @rendered = (total - remaining).fdiv(player.clock_hz)
+          @observer.call(samples, @rendered)
+          yield(@rendered < @from ? [] : samples, @rendered)
+          break if fallen_silent?(samples)
+        end
+      end
+
+      # Counts the samples since the output last strayed more than QUIET
+      # from where it settled.
+      def fallen_silent?(samples)
+        return false if @silent_samples.zero? || samples.empty?
+
+        if samples.max - @level > QUIET || @level - samples.min > QUIET
+          @level = samples.last
+          @still = 0
+        else
+          @still += samples.length / 2
         end
+        @still >= @silent_samples
       end
     end
   end

data/lib/badline/audio/stereo.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # The SIDs a tune plays on, the bus's own first and the extra ones at
+    # the addresses the tune's header gives, each on its own model. Their
+    # output mixes to interleaved stereo: SID 1 on the left, SID 2 on the
+    # right and SID 3 in the centre, at half on each side. A tune on one SID
+    # plays the same on both channels.
+    class Stereo
+      # The SIDs, in the order the header numbers them.
+      attr_reader :sids
+
+      # Each SID's own samples, as the last #mix drained them.
+      attr_reader :outputs
+
+      def initialize(bus, tune, models)
+        @sids = [bus.sid]
+        @extras = []
+        tune.sid_addresses.each do |address|
+          sid = SID.new(model: models[@sids.size], at: address)
+          bus.add_sid(sid)
+          @sids << sid
+          @extras << sid
+        end
+        @fitted = models
+        @outputs = []
+      end
+
+      # The SIDs past the bus's own, which the player clocks itself.
+      attr_reader :extras
+
+      def synthesize! = @sids.each(&:synthesize!)
+
+      # The model each SID plays on.
+      def models = @sids.map(&:model)
+
+      # Puts every SID on `model`, or with :auto each back on the one it was
+      # fitted with.
+      def refit(model)
+        @sids.size.times do |index|
+          wanted = model == :auto ? @fitted[index] : model
+          sid = @sids[index]
+          sid.model = wanted unless sid.model == wanted
+        end
+      end
+
+      def record(rate:, filter_chunk:, clock_hz:)
+        @sids.each { |sid| sid.record(rate:, filter_chunk:, clock_hz:) }
+      end
+
+      # Drains every SID and yields the left and the right of each sample
+      # in turn.
+      def mix(&)
+        outputs = @outputs
+        outputs.clear
+        @sids.each { |sid| outputs << sid.drain_samples }
+        case outputs.size
+        when 1 then both(outputs[0], &)
+        when 2 then pair(outputs[0], outputs[1], &)
+        else centred(outputs[0], outputs[1], outputs[2], &)
+        end
+      end
+
+      private
+
+      def both(samples)
+        i = 0
+        while i < samples.size
+          yield samples[i]
+          yield samples[i]
+          i += 1
+        end
+      end
+
+      def pair(left, right)
+        count = [left.size, right.size].min
+        i = 0
+        while i < count
+          yield left[i]
+          yield right[i]
+          i += 1
+        end
+      end
+
+      def centred(left, right, centre)
+        count = [left.size, right.size, centre.size].min
+        i = 0
+        while i < count
+          yield ((2 * left[i]) + centre[i]) / 3
+          yield ((2 * right[i]) + centre[i]) / 3
+          i += 1
+        end
+      end
+    end
+  end
+end