badline 0.6.1 → 0.7.0

data/lib/badline/audio/cli.rb

@@ -2,14 +2,14 @@
 
 module Badline
   module Audio
-    # Runs `--headless` or `--audio-out`, in either build, once its options
-    # have parsed: picks the song and its length, then plays it or renders
-    # it to a file. Played on a terminal, the console lets the listener step
-    # between songs.
+    # Runs `--headless`, `--audio-out` or `sid`, in either build, once its
+    # options have parsed: queues the tunes, each with its subtune and length,
+    # then plays them or renders the one to a file. Played on a terminal,
+    # the console lets the listener step through the queue.
     class CLI
       class Error < StandardError; end
 
-      # Plays or renders the tune as #run does, reports an error on stderr
+      # Plays or renders the tunes as #run does, reports an error on stderr
       # under the program's name, and returns the exit status.
       def self.run(options, sink:, console:)
         new(options, sink:, console:).run
@@ -33,55 +33,84 @@ module Badline
         @input = input
         @sink = sink
         @console = console
-        @lengths = {}
+        @announced = nil
+        @terminal = nil
+        @stil_lists = {}
       end
 
       def run
         @options.render? ? render : play
-      rescue Renderer::UnknownFormatError, Storage::SIDFile::FormatError => e
+      rescue Renderer::UnknownFormatError => e
         raise Error, e.message
       end
 
-      def tune
-        @tune ||= Storage::SIDFile.new(@options.tune_path)
-      rescue Storage::SIDFile::FormatError => e
-        raise Error, "#{@options.tune_path}: #{e.message}"
-      end
+      # The tunes to play, in the order given. --subtune picks the first
+      # one's subtune.
+      def queue
+        @queue ||= begin
+          paths = @options.tune_paths
+          queue = Media::Queue.new(entries(paths, @options.subtune), all_parts: @options.all_subtunes?,
+                                                                     build: ->(dropped) { entries(dropped) })
+          raise Error, "no .sid tunes in #{paths.join(', ')}" if queue.empty? && !paths.empty?
 
-      def song
-        @song ||= (@options.song || tune.start_song).tap do |song|
-          raise Error, "no song #{song}: the tune has #{tune.songs}" if song > tune.songs
+          queue
         end
       end
 
-      def seconds = length(song)
+      def tune = checked(queue.entry).tune
 
-      def length(song)
-        @lengths[song] ||= @options.seconds || songlength(song) || @options.fallback_seconds
-      end
+      def subtune = checked(queue.entry).part
+
+      def seconds = length(subtune)
+
+      def length(subtune) = queue.entry.length(subtune)
+
+      def silence(subtune) = queue.entry.silence(subtune)
 
-      def sid_model = @options.sid_model || tune.sid_model
+      def sid_models = queue.entry.sid_models
 
-      def interactive? = @options.tui? && @input.tty? && @out.tty?
+      def interactive? = @options.player_window? || (@options.tui? && @input.tty? && @out.tty?)
 
       private
 
-      def renderer(song, rate)
-        Renderer.new(tune, seconds: length(song), song:, rate:, sid_model:).tap do |renderer|
-          renderer.filter_chunk = @options.filter_chunk if @options.filter_chunk
+      # The tunes in the paths, the files themselves and the .sid files
+      # below the directories, the first starting on `subtune` if given.
+      def entries(paths, subtune = nil)
+        tunes = []
+        Media::Queue.files(paths, ".sid").each do |path|
+          tunes << QueuedTune.new(path, @options, subtune: tunes.empty? ? subtune : nil)
         end
+        tunes
+      end
+
+      # A tune on its own has to play, where one of many is skipped.
+      def checked(entry)
+        raise Error, "#{entry.path}: #{entry.error}" unless entry.error.empty?
+
+        entry
+      end
+
+      def renderer(entry, subtune, rate)
+        renderer = Renderer.new(entry.tune, seconds: entry.length(subtune), subtune:, rate:,
+                                            sid_models: entry.sid_models)
+        renderer.filter_chunk = @options.filter_chunk if @options.filter_chunk
+        renderer.silence = entry.silence(subtune) if entry.silence(subtune)
+        renderer
       end
 
       def render
-        renderer = renderer(song, @options.rate)
-        @out.puts describe
-        @out.puts "Rendering #{seconds}s for the #{model_name} to #{@options.audio_out} at #{@options.rate} Hz..."
+        entry = checked(queue.entry)
+        renderer = renderer(entry, subtune, @options.rate)
+        @out.puts describe(entry, subtune)
+        @out.puts "Rendering #{seconds}s for the #{entry.model_name} to #{@options.audio_out} " \
+                  "at #{@options.rate} Hz..."
         started = now
-        renderer.render(@options.audio_out) { |done| progress(done) }
-        report(now - started)
+        renderer.render(@options.audio_out) { |done| progress(done, seconds) }
+        report(renderer.rendered, now - started)
       end
 
       def play
+        checked(queue.entry) if queue.size == 1
         sink = open_sink
         interactive? ? play_interactively(sink) : play_plainly(sink)
       ensure
@@ -89,23 +118,85 @@ module Badline
       end
 
       def play_plainly(sink)
-        @out.puts describe
-        @out.puts "Playing #{seconds}s on the #{model_name} at #{sink.rate} Hz. Ctrl-C stops."
-        playback = Playback.new(sink, on_underrun: -> { @out.puts "\rRunning below real time, so it will stutter." })
-        result = playback.play(renderer(song, sink.rate)) { |played| progress(played) }
-        progress(seconds) if result == :finished
+        loop do
+          result = play_subtune(sink, queue.entry, queue.part)
+          break unless %i[finished skipped].include?(result) && queue.advance
+        end
+      end
+
+      def play_subtune(sink, entry, subtune)
+        return skip(entry) unless entry.error.empty?
+
+        announce(entry, subtune)
+        subtune_comments(entry, subtune).each { |line| @out.puts line }
+        length = entry.length(subtune)
+        @out.puts "Playing #{length}s on the #{entry.model_name} at #{sink.rate} Hz. Ctrl-C stops."
+        @warned = false
+        playback = Playback.new(sink, on_underrun: -> { warn_below_real_time })
+        renderer = renderer(entry, subtune, sink.rate)
+        result = playback.play(renderer) { |played| progress(played, length) }
+        progress(renderer.rendered, length) if result == :finished
         @out.print "\n" unless @options.quiet?
         @out.puts(result == :finished ? "Done." : "Stopped.")
+        result
+      end
+
+      def warn_below_real_time
+        return if @warned
+
+        @warned = true
+        @out.puts "\rRunning below real time, so it will stutter."
+      end
+
+      def skip(entry)
+        @out.puts "Skipping #{entry.path}: #{entry.error}"
+        :skipped
+      end
+
+      def announce(entry, subtune)
+        @out.puts describe(entry, subtune)
+        return if entry.equal?(@announced)
+
+        @announced&.release
+        @announced = entry
+        comments(entry).each { |line| @out.puts line }
       end
 
       def play_interactively(sink)
-        console = @console.call(input: @input, output: @out)
-        jukebox = Jukebox.new(sink, console, songs: tune.songs, renderer: method(:renderer), length: method(:length))
-        console.session do
-          console.header([tune.name, tune.author, tune.released].reject(&:empty?) +
-                         ["#{model_name} at #{sink.rate} Hz"])
-          jukebox.run(song)
-        end
+        @terminal = @console.call(input: @input, output: @out)
+        jukebox = Jukebox.new(sink, @terminal, queue:,
+                                               renderer: ->(entry, subtune, rate) { playable(entry, subtune, rate) },
+                                               length: ->(entry, subtune) { entry.length(subtune) })
+        @terminal.session { jukebox.run }
+      end
+
+      # The renderer for the subtune, or nil for a tune the jukebox skips.
+      def playable(entry, subtune, rate)
+        introduce(entry, rate) unless entry.equal?(@announced)
+        return nil unless entry.error.empty?
+
+        comments = subtune_comments(entry, subtune)
+        @terminal.announce(comments) unless comments.empty?
+        renderer = renderer(entry, subtune, rate)
+        found = stil(entry)
+        @terminal.stil(found ? found.fields : [], subtune, found ? found.subtune(subtune) : [])
+        @terminal.playing(renderer)
+        renderer
+      end
+
+      # Shows the tune's header above the status line as it starts, below
+      # the keys the first time.
+      def introduce(entry, rate)
+        @announced&.release
+        lines = introduction(entry, rate)
+        @announced.nil? ? @terminal.header(lines) : @terminal.announce(lines)
+        @announced = entry
+      end
+
+      def introduction(entry, rate)
+        return ["Skipping #{entry.path}: #{entry.error}"] unless entry.error.empty?
+
+        entry.header + ["#{entry.model_name} at #{rate} Hz"] + comments(entry)
       end
 
       def open_sink
@@ -114,36 +205,40 @@ module Badline
         raise Error, "can't open the audio device: #{e.message}"
       end
 
-      def describe
-        header = [tune.name, tune.author, tune.released].reject(&:empty?).join(" / ")
-        header.empty? ? "song #{song}" : "#{header} (song #{song})"
+      def describe(entry, subtune)
+        header = entry.header.join(" / ")
+        header.empty? ? "subtune #{subtune}" : "#{header} (subtune #{subtune})"
       end
 
-      # HVSC's database is keyed by the tune's MD5 and lists one length per
-      # song.
-      def songlength(song) = songlengths&.at(song - 1)
-
-      def songlengths
-        return @songlengths if @songlengths_read
+      # The tune's entry in HVSC's STIL, as STIL.txt lays it out.
+      def comments(entry)
+        found = stil(entry)
+        found ? found.fields.flat_map(&:lines) : []
+      end
 
-        @songlengths_read = true
-        path = @options.songlengths || Storage::SongLengths.locate(@options.tune_path)
-        @songlengths = path && Storage::SongLengths.new(path).lengths(tune.md5)
+      def subtune_comments(entry, subtune)
+        found = stil(entry)
+        lines = found ? found.subtune(subtune).flat_map(&:lines) : []
+        lines.empty? ? lines : ["(##{subtune})"] + lines
       end
 
-      def model_name = sid_model.to_s.delete_prefix("mos")
+      def stil(entry)
+        list = Storage::STIL.locate(entry.path)
+        hvsc_path = list && Storage::HVSC.path(entry.path, list)
+        hvsc_path && (@stil_lists[list] ||= Storage::STIL.new(list)).entry(hvsc_path)
+      end
 
-      def progress(done)
+      def progress(done, total)
         return if @options.quiet?
 
-        @out.print format("\r%<done>6.1fs / %<total>.1fs", done:, total: seconds)
+        @out.print format("\r%<done>6.1fs / %<total>.1fs", done:, total:)
         @out.flush
       end
 
-      def report(elapsed)
+      def report(rendered, elapsed)
         @out.print "\r" unless @options.quiet?
         @out.puts format("Wrote %<path>s in %<elapsed>.1fs (%<speed>.2fx real time).",
-                         path: @options.audio_out, elapsed:, speed: seconds / elapsed)
+                         path: @options.audio_out, elapsed:, speed: rendered / elapsed)
       end
 
       def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)

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