badline 0.6.1 → 0.7.0

data/lib/badline/frontend/info_view.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Badline
+  module Frontend
+    # The SID player's INFO view: the tune's STIL entry, and the playing
+    # subtune's, laid out as STIL.txt lays them out but reflowed to the
+    # window's width. A line of STIL's that runs to its width goes on into
+    # the next, and a shorter one ends a paragraph. Text longer than the view
+    # scrolls, by the wheel, the up and down keys, or a click or drag along
+    # the scroll bar beside it.
+    class InfoView
+      HEIGHT = VisualizerView::HEIGHT
+      LINE = 10
+      ROWS = HEIGHT / LINE
+      LEFT = SIDView::LEFT
+      BAR = 6
+      BAR_LEFT = PlayerHeader::WIDTH - 16 - BAR
+      COLUMNS = (BAR_LEFT - LEFT - 8) / Painter::GLYPH
+      LABEL = 9
+
+      # How long a line of STIL's is when it runs on into the next.
+      FULL = 60
+
+      attr_reader :offset
+
+      def initialize(painter, buttons, top)
+        @painter = painter
+        @buttons = buttons
+        @top = top
+        @lines = []
+        @offset = 0
+      end
+
+      # Shows the tune's fields, then the subtune's under its number, from
+      # the top.
+      def show(fields, subtune, subtune_fields)
+        lines = InfoView.layout(fields)
+        lines += ["", "(##{subtune})"] + InfoView.layout(subtune_fields) unless subtune_fields.empty?
+        @lines = lines.empty? ? ["No STIL entry for this tune."] : lines
+        @offset = 0
+      end
+
+      def scroll(rows)
+        @offset = (@offset + rows).clamp(0, last_offset)
+      end
+
+      # Scrolls to the place `top` points at along the scroll bar.
+      def scroll_along(top)
+        @offset = ((top - @top).to_f / HEIGHT * @lines.size).round.clamp(0, last_offset)
+      end
+
+      def draw
+        index = 0
+        while index < ROWS && @offset + index < @lines.size
+          @painter.text(LEFT, @top + (index * LINE), @lines[@offset + index], SIDView::TEXT)
+          index += 1
+        end
+        draw_bar if @lines.size > ROWS
+      end
+
+      # Each field's label, right-aligned as in STIL.txt, before its text
+      # reflowed into the columns beside it.
+      def self.layout(fields)
+        lines = []
+        fields.each do |field|
+          label = "#{field.name}:".rjust(LABEL - 1)
+          paragraphs(field.text).each do |paragraph|
+            wrap(paragraph, COLUMNS - LABEL).each do |line|
+              lines << "#{label} #{line}"
+              label = " " * (LABEL - 1)
+            end
+          end
+        end
+        lines
+      end
+
+      # The text's lines joined where one ran to STIL's width.
+      def self.paragraphs(text)
+        paragraphs = []
+        full = false
+        text.split("\n").each do |line|
+          if full
+            paragraphs[-1] = "#{paragraphs[-1]} #{line.strip}"
+          else
+            paragraphs << line.strip
+          end
+          full = line.length >= FULL
+        end
+        paragraphs
+      end
+
+      # The text broken at spaces into lines of at most `columns`, and a word
+      # longer than that broken where it has to be.
+      def self.wrap(text, columns)
+        lines = []
+        rest = text
+        while rest.length > columns
+          cut = rest.rindex(" ", columns)
+          cut = columns if cut.nil? || cut.zero?
+          lines << rest[0, cut].rstrip
+          rest = rest[cut, rest.length - cut].lstrip
+        end
+        lines << rest
+        lines
+      end
+
+      private
+
+      def last_offset = [@lines.size - ROWS, 0].max
+
+      def draw_bar
+        @buttons.area([BAR_LEFT, @top, BAR, HEIGHT], :scroll)
+        @painter.box(BAR_LEFT, @top, BAR, HEIGHT, SIDView::BOX)
+        thumb = [HEIGHT * ROWS / @lines.size, 8].max
+        place = (HEIGHT - thumb) * @offset / [last_offset, 1].max
+        @painter.box(BAR_LEFT, @top + place, BAR, thumb, SIDView::TEXT)
+      end
+    end
+  end
+end

data/lib/badline/frontend/painter.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Badline
+  module Frontend
+    # Draws on an SDL renderer in the C64's colours and its character ROM's
+    # font: filled boxes, lines and text. The font is the ROM's second set,
+    # with both cases, turned into a texture once: 16 by 16 glyphs of 8 by 8
+    # pixels, white where the glyph is set and clear elsewhere, tinted to
+    # the colour asked for as each glyph is drawn.
+    class Painter
+      GLYPH = 8
+      ATLAS = GLYPH * 16
+
+      # An opaque white pixel, in the low half of a word and in the high
+      # half, where it only fits a signed 64-bit word as a negative number.
+      SET = 0xffffffff
+      SET_HIGH = -0x1_0000_0000
+
+      SPACE = 0x20
+
+      # Icons drawn in the C64's 8 by 8 cells, which take the places of the
+      # first reversed glyphs, from ICON on.
+      ICON = 0x80
+      ICONS = {
+        play: %w[.X...... .XX..... .XXX.... .XXXX... .XXXX... .XXX.... .XX..... .X......],
+        pause: %w[........ .XX..XX. .XX..XX. .XX..XX. .XX..XX. .XX..XX. .XX..XX. ........],
+        previous: %w[X.....X. X....XX. X...XXX. X..XXXX. X..XXXX. X...XXX. X....XX. X.....X.],
+        next: %w[.X.....X .XX....X .XXX...X .XXXX..X .XXXX..X .XXX...X .XX....X .X.....X],
+        left: %w[........ ....X... ...XX... ..XXX... ..XXX... ...XX... ....X... ........],
+        right: %w[........ ...X.... ...XX... ...XXX.. ...XXX.. ...XX... ...X.... ........]
+      }.freeze
+      ICON_NAMES = ICONS.keys.freeze
+
+      # The screen code of each printable ASCII character in the second set.
+      # The rest show as a question mark.
+      SCREEN_CODES = Array.new(128) do |ascii|
+        if ascii.between?(0x20, 0x3f) || ascii.between?(0x41, 0x5a) then ascii
+        elsif ascii == 0x40 then 0
+        elsif ascii.between?(0x61, 0x7a) then ascii - 0x60
+        elsif ascii == 0x5b then 27
+        elsif ascii == 0x5d then 29
+        elsif ascii == 0x5e then 30
+        elsif ascii == 0x5f then 100
+        else 63
+        end
+      end.freeze
+
+      def initialize(renderer)
+        @renderer = renderer
+        @font = SDL.SDL_CreateTexture(renderer, SDL::PIXELFORMAT_ARGB8888, SDL::TEXTUREACCESS_STREAMING, ATLAS, ATLAS)
+        SDL.SDL_SetTextureBlendMode(@font, SDL::BLENDMODE_BLEND)
+        load_font
+        SDL.rect_w(SDL.glyph_rect, GLYPH)
+        SDL.rect_h(SDL.glyph_rect, GLYPH)
+        @tint = -1
+        @size = 0
+      end
+
+      def close = SDL.SDL_DestroyTexture(@font)
+
+      def box(left, top, width, height, rgb)
+        @size = 0
+        rect = SDL.rect
+        SDL.rect_x(rect, left)
+        SDL.rect_y(rect, top)
+        SDL.rect_w(rect, width)
+        SDL.rect_h(rect, height)
+        pen(rgb)
+        SDL.SDL_RenderFillRect(@renderer, rect)
+      end
+
+      # Joins the points, each made by Painter.point, with lines.
+      def polyline(points, rgb)
+        pen(rgb)
+        SDL.SDL_RenderDrawLines(@renderer, points, points.size)
+      end
+
+      # A point for #polyline: an SDL_Point, two 32-bit ints packed into one
+      # of the words an Integer Array hands to C, x in the low half.
+      def self.point(left, top) = left | (top << 32)
+
+      # Draws the text with its top left at `left` and `top`, each glyph
+      # `scale` times its size, and returns the width drawn.
+      def text(left, top, string, rgb, scale: 1)
+        tint(rgb)
+        place(top, GLYPH * scale)
+        x = left
+        string.each_char do |char|
+          code = screen_code(char)
+          glyph(code, x) unless code == SPACE
+          x += @size
+        end
+        x - left
+      end
+
+      def self.width(string, scale: 1) = string.length * GLYPH * scale
+
+      def icon(name, left, top, rgb, scale: 1)
+        tint(rgb)
+        place(top, GLYPH * scale)
+        glyph(ICON + ICON_NAMES.index(name), left)
+      end
+
+      private
+
+      def screen_code(char)
+        ascii = char.ord
+        ascii < 128 ? SCREEN_CODES[ascii] : 63
+      end
+
+      # Sets the row and size glyphs go at, which a run of text shares.
+      def place(top, size)
+        to = SDL.rect
+        SDL.rect_y(to, top)
+        return if size == @size
+
+        @size = size
+        SDL.rect_w(to, size)
+        SDL.rect_h(to, size)
+      end
+
+      def glyph(code, left)
+        from = SDL.glyph_rect
+        SDL.rect_x(from, (code % 16) * GLYPH)
+        SDL.rect_y(from, (code / 16) * GLYPH)
+        to = SDL.rect
+        SDL.rect_x(to, left)
+        SDL.SDL_RenderCopy(@renderer, @font, from, to)
+      end
+
+      def pen(rgb)
+        SDL.SDL_SetRenderDrawColor(@renderer, (rgb >> 16) & 0xff, (rgb >> 8) & 0xff, rgb & 0xff, 255)
+      end
+
+      def tint(rgb)
+        return if rgb == @tint
+
+        @tint = rgb
+        SDL.SDL_SetTextureColorMod(@font, (rgb >> 16) & 0xff, (rgb >> 8) & 0xff, rgb & 0xff)
+      end
+
+      # Two pixels to a word, the left one in the low half, as Screen packs
+      # them.
+      def load_font
+        rom = ROM.read("character.rom")
+        words = Array.new(ATLAS * ATLAS / 2, 0)
+        256.times { |code| unpack_glyph(rom[0x800 + (code * GLYPH), GLYPH], code, words) }
+        ICON_NAMES.each_with_index { |name, index| unpack_glyph(icon_rows(name), ICON + index, words) }
+        rect = SDL.glyph_rect
+        SDL.rect_x(rect, 0)
+        SDL.rect_y(rect, 0)
+        SDL.rect_w(rect, ATLAS)
+        SDL.rect_h(rect, ATLAS)
+        SDL.SDL_UpdateTexture(@font, rect, words, ATLAS * 4)
+      end
+
+      def icon_rows(name)
+        ICONS.fetch(name).map { |row| row.tr(".X", "01").to_i(2) }
+      end
+
+      def unpack_glyph(rows, code, words)
+        GLYPH.times do |row|
+          bits = rows[row]
+          y = ((code / 16) * GLYPH) + row
+          x = (code % 16) * GLYPH
+          4.times do |pair|
+            left = bits[7 - (pair * 2)] == 1 ? SET : 0
+            right = bits[6 - (pair * 2)] == 1 ? SET_HIGH : 0
+            words[(((y * ATLAS) + x) / 2) + pair] = left | right
+          end
+        end
+      end
+    end
+  end
+end

data/lib/badline/frontend/player_commands.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Badline
+  module Frontend
+    # What the SID player's window does with an action a key or a click asks
+    # for: one that picks or steps through the views or the SID models, or
+    # picks the SID shown, changes the PlayerState, and any other goes on to
+    # the jukebox.
+    class PlayerCommands
+      VIEWS = PlayerHeader::VIEWS
+      CHIPS = PlayerHeader::CHIPS
+      SIDS = SIDView::SIDS
+
+      def initialize(state)
+        @state = state
+      end
+
+      # Returns the action for the jukebox, or nil when the window has
+      # handled it.
+      def handle(action)
+        state = @state
+        if action == :view then state.view = (state.view + 1) % VIEWS.size
+        elsif action == :chip then state.chip = (state.chip + 1) % CHIPS.size
+        elsif VIEWS.include?(action) then state.view = VIEWS.index(action)
+        elsif CHIPS.include?(action) then state.chip = CHIPS.index(action)
+        elsif SIDS.include?(action) then state.sid = SIDS.index(action)
+        else return action
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/badline/frontend/player_footer.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Badline
+  module Frontend
+    # The bottom of the SID player's window: how far the subtune has played,
+    # on a bar a click seeks along, marked with where a seek is headed, and the buttons that pause and step
+    # through the queue's tunes and the tune's subtunes and turn the queue's
+    # modes on and off.
+    class PlayerFooter
+      HEIGHT = 44
+      WIDTH = PlayerHeader::WIDTH
+      CLOCK = "00:00 / 00:00"
+      BAR_LEFT = 16
+      BAR_WIDTH = WIDTH - 32 - (CLOCK.length * Painter::GLYPH) - 8
+      TOGGLES = ["SHUFFLE", "LOOP", "ALL SUBTUNES"].freeze
+      TOGGLE_ACTIONS = %i[shuffle loop all_subtunes].freeze
+      TOGGLE_NOTES = ["shuffle", "loop", "all subtunes"].freeze
+
+      def initialize(painter, buttons)
+        @painter = painter
+        @buttons = buttons
+      end
+
+      def draw(state, top)
+        draw_progress(state, top + 4)
+        row = top + 18
+        x = 12
+        x += @buttons.icon(x, row, :previous, :previous, scale: 2) + 4
+        x += @buttons.icon(x, row, state.paused? ? :play : :pause, :pause, scale: 2) + 4
+        x += @buttons.icon(x, row, :next, :next, scale: 2) + 8
+        unless state.tunes.zero?
+          x += @painter.text(x, row + 6, "TUNE #{state.tune}/#{state.tunes}", SIDView::BRIGHT) + 24
+          draw_subtunes(state, x, row + 4)
+        end
+        draw_toggles(state, row + 4)
+      end
+
+      # The seconds into the subtune a click `left` along the bar asks for.
+      def self.seek(left, length) = ((left - BAR_LEFT).to_f / BAR_WIDTH).clamp(0.0, 1.0) * length
+
+      private
+
+      def draw_subtunes(state, left, row)
+        x = left + @painter.text(left, row + 2, "SUBTUNE", SIDView::TEXT) + 4
+        x += @buttons.icon(x, row, :left, :previous_subtune)
+        x += @painter.text(x + 2, row + 2, "#{state.subtune}/#{state.subtunes}", SIDView::BRIGHT) + 4
+        @buttons.icon(x, row, :right, :next_subtune)
+      end
+
+      def draw_progress(state, top)
+        played = state.played
+        width = BAR_WIDTH
+        @buttons.area([BAR_LEFT, top - 2, width, 12], :seek)
+        @painter.box(BAR_LEFT, top + 2, width, 4, SIDView::BOX)
+        draw_target(state, top) if state.seeking?
+        @painter.box(BAR_LEFT, top + 2, along(state, played), 4, SIDView::BRIGHT)
+        @painter.text(WIDTH - 16 - Painter.width(CLOCK), top, "#{clock(played)} / #{clock(state.length)}",
+                      SIDView::TEXT)
+      end
+
+      def draw_target(state, top)
+        target = along(state, state.target)
+        @painter.box(BAR_LEFT, top + 2, target, 4, SIDView::DIM)
+        @painter.box(BAR_LEFT + [target, BAR_WIDTH - 1].min, top - 1, 1, 10, SIDView::BRIGHT)
+      end
+
+      # How far along the bar `seconds` into the subtune is.
+      def along(state, seconds)
+        length = state.length
+        length.positive? ? (BAR_WIDTH * seconds / length).round.clamp(0, BAR_WIDTH) : 0
+      end
+
+      def draw_toggles(state, row)
+        x = PlayerHeader.right_aligned(TOGGLES)
+        TOGGLES.each_with_index do |label, toggle|
+          x += @buttons.text(x, row, label, TOGGLE_ACTIONS[toggle], on: state.on?(TOGGLE_NOTES[toggle])) + 4
+        end
+      end
+
+      def clock(seconds)
+        whole = seconds.floor
+        format("%<minutes>d:%<seconds>02d", minutes: whole / 60, seconds: whole % 60)
+      end
+    end
+  end
+end

data/lib/badline/frontend/player_header.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Badline
+  module Frontend
+    # The top of the SID player's window: the tune's name, author and
+    # release, the STIL credit for what the subtune covers at the moment, a
+    # warning when there is one, and the buttons for the views and the SID
+    # model.
+    class PlayerHeader
+      WIDTH = 640
+      VIEW_NAMES = %w[VISUALIZER SID INFO].freeze
+      VIEWS = %i[visualizer sid info].freeze
+      CHIP_NAMES = %w[AUTO 6581 8580].freeze
+      CHIPS = %i[auto mos6581 mos8580].freeze
+
+      def initialize(painter, buttons)
+        @painter = painter
+        @buttons = buttons
+      end
+
+      # Underlines the models playing while AUTO picks them.
+      def draw(state, tune, playing_models, credit)
+        unless tune.nil?
+          @painter.text(16, 8, fit(tune.name, 26), SIDView::BRIGHT, scale: 2)
+          @painter.text(16, 28, fit([tune.author, tune.released].reject(&:empty?).join(" - "), 50), SIDView::TEXT)
+          @painter.text(16, 40, fit(credit, 76), SIDView::BRIGHT)
+          @painter.text(16, 52, warning(state), PlayerWindow::WARNING)
+        end
+        draw_views(state)
+        draw_chips(state, playing_models)
+      end
+
+      def self.right_aligned(labels) = WIDTH - 12 - labels.sum { |label| Painter.width(label) + 8 }
+
+      private
+
+      def warning(state) = state.on?("below real time") ? "Running below real time" : ""
+
+      def draw_views(state)
+        x = PlayerHeader.right_aligned(VIEW_NAMES)
+        VIEW_NAMES.each_with_index do |name, view|
+          x += @buttons.text(x, 6, name, VIEWS[view], on: view == state.view) + 4
+        end
+      end
+
+      def draw_chips(state, playing_models)
+        x = PlayerHeader.right_aligned(CHIP_NAMES)
+        CHIP_NAMES.each_with_index do |name, chip|
+          width = @buttons.text(x, 24, name, CHIPS[chip], on: chip == state.chip)
+          if state.chip.zero? && playing_models.include?(CHIPS[chip])
+            @painter.box(x + 2, 37, width - 4, 1, SIDView::BRIGHT)
+          end
+          x += width + 4
+        end
+      end
+
+      def fit(text, chars) = text.length > chars ? "#{text[0, chars - 2]}.." : text
+    end
+  end
+end

data/lib/badline/frontend/player_screen.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Badline
+  module Frontend
+    # The SDL window the SID player draws in, and its drawing: the header,
+    # the body of the view picked, and the footer, at the height the view
+    # needs, in logical pixels scaled up twice.
+    class PlayerScreen
+      WIDTH = PlayerHeader::WIDTH
+      HEADER = 64
+      SCALE = 2
+      TITLE = "Badline"
+      BACKGROUND = Screen::COLORS[6]
+
+      attr_reader :buttons, :info
+
+      def initialize
+        @window = nil
+        @renderer = nil
+        @painter = nil
+        @buttons = nil
+        @info = nil
+        @sids = 1
+      end
+
+      def open?
+        !@window.nil?
+      end
+
+      def open(view)
+        SDL.SDL_InitSubSystem(SDL::INIT_VIDEO | SDL::INIT_EVENTS)
+        SDL.SDL_SetHint("SDL_RENDER_SCALE_QUALITY", "0")
+        @window = SDL.SDL_CreateWindow(TITLE, SDL::WINDOWPOS_CENTERED, SDL::WINDOWPOS_CENTERED,
+                                       WIDTH * SCALE, height(view) * SCALE, SDL::WINDOW_RESIZABLE)
+        @renderer = SDL.SDL_CreateRenderer(@window, -1, SDL::RENDERER_ACCELERATED)
+        SDL.SDL_RenderSetLogicalSize(@renderer, WIDTH, height(view))
+        build
+      end
+
+      def close
+        return unless open?
+
+        @painter.close
+        SDL.SDL_DestroyRenderer(@renderer)
+        SDL.SDL_DestroyWindow(@window)
+        SDL.SDL_QuitSubSystem(SDL::INIT_VIDEO | SDL::INIT_EVENTS)
+        @window = nil
+      end
+
+      # Fits the window to the view's height.
+      def resize(view)
+        SDL.SDL_SetWindowSize(@window, WIDTH * SCALE, height(view) * SCALE)
+        SDL.SDL_RenderSetLogicalSize(@renderer, WIDTH, height(view))
+      end
+
+      # Fits the window to a tune on `sids` SIDs, whose SID view is taller
+      # than one on a single SID.
+      def fit_sids(view, sids)
+        return if sids == @sids
+
+        @sids = sids
+        resize(view) if open?
+      end
+
+      # Names the tune in the window's title.
+      def title(name)
+        SDL.SDL_SetWindowTitle(@window, name.empty? ? TITLE : "#{name} - #{TITLE}") if open?
+      end
+
+      # Draws a frame of the player: `player` and `history` are the SIDs',
+      # nil before anything plays, and `credit` the header's STIL credit.
+      def draw(state, player, history, tune, credit)
+        return unless open?
+
+        SDL.SDL_SetRenderDrawColor(@renderer, (BACKGROUND >> 16) & 0xff, (BACKGROUND >> 8) & 0xff,
+                                   BACKGROUND & 0xff, 255)
+        SDL.SDL_RenderClear(@renderer)
+        @buttons.forget
+        @top.draw(state, tune, player.nil? ? [] : player.stereo.models, credit)
+        player.nil? ? draw_empty(state.view) : draw_body(state, player, history)
+        @bottom.draw(state, height(state.view) - PlayerFooter::HEIGHT)
+        SDL.SDL_RenderPresent(@renderer)
+      end
+
+      private
+
+      def height(view) = HEADER + body_height(view) + PlayerFooter::HEIGHT
+
+      def body_height(view) = view == 1 ? SIDView.height(@sids) : VisualizerView::HEIGHT
+
+      def build
+        @painter = Painter.new(@renderer)
+        @buttons = Buttons.new(@painter)
+        @top = PlayerHeader.new(@painter, @buttons)
+        @bottom = PlayerFooter.new(@painter, @buttons)
+        @visualizer = VisualizerView.new(@painter, HEADER + 4)
+        @sid_view = SIDView.new(@painter, @buttons, HEADER + 4)
+        @info = InfoView.new(@painter, @buttons, HEADER + 4)
+      end
+
+      def draw_body(state, player, history)
+        played = state.played
+        case state.view
+        when 0 then @visualizer.draw(history, played, clock_hz: player.clock_hz)
+        when 1 then draw_sid(state.sid, player, history, played)
+        else @info.draw
+        end
+      end
+
+      # The SID view of the SID picked, or of the last a tune has.
+      def draw_sid(sid, player, history, played)
+        models = player.stereo.models
+        shown = [sid, models.size - 1].min
+        @sid_view.draw(history, played, clock_hz: player.clock_hz, model: models[shown], sid: shown)
+      end
+
+      def draw_empty(view)
+        hint = "Drop .sid files or folders here"
+        @painter.text((WIDTH - Painter.width(hint, scale: 2)) / 2, HEADER + (body_height(view) / 2) - 8, hint,
+                      SIDView::TEXT, scale: 2)
+      end
+    end
+  end
+end

data/lib/badline/frontend/player_state.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Badline
+  module Frontend
+    # What the SID player's window shows about playback: the subtune and the
+    # tune's place in the queue, the time, the modes the jukebox reports
+    # as notes, the view and SID model chosen, which of a tune's SIDs the
+    # SID view shows, and where a seek is headed until playback gets there.
+    class PlayerState
+      attr_accessor :subtune, :subtunes, :tune, :tunes, :length, :notes, :view, :chip, :sid
+      attr_reader :target
+
+      def initialize
+        @subtune = 0
+        @subtunes = 0
+        @tune = 0
+        @tunes = 0
+        @length = 0.0
+        @notes = []
+        @view = 0
+        @chip = 0
+        @sid = 0
+        @elapsed = 0.0
+        @elapsed_at = now
+        @target = 0.0
+        @below = false
+      end
+
+      # The seconds heard as the jukebox last reported them.
+      def elapsed=(seconds)
+        @elapsed = seconds
+        @elapsed_at = now
+        return unless seeking?
+
+        @below ||= seconds < @target
+        stop_seeking if @below && seconds >= @target
+      end
+
+      # Notes a seek to `seconds`, which lasts until playback has come up
+      # to it from below.
+      def seek(seconds)
+        @target = seconds
+        @below = false
+      end
+
+      def stop_seeking = @target = 0.0
+
+      def seeking? = @target.positive?
+
+      # The seconds heard so far: the last reported, carried on by the
+      # clock unless it is paused.
+      def played
+        return @elapsed if paused?
+
+        [@elapsed + (now - @elapsed_at), @length].min
+      end
+
+      def paused? = on?("paused")
+
+      def on?(note) = @notes.include?(note)
+
+      private
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end