segue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 654226acfd8c43958144ae5f8bd900a574d9535063718086869a1b7a561fc65e
+  data.tar.gz: d575d92843c8dcfc7063e0fe75a753b4f9d342ac32861319d07a9a7841b11658
+SHA512:
+  metadata.gz: e0adbfd5b037b62276113137e8fbaa06f5bd904e7fcca18d69e9978123f8cdd3f335e95a8e3be52abbbb5348293710ffefced2dee955f365c186fce29f6a19cc
+  data.tar.gz: ef84a246e55156861643f8a2ca644a70a19473f6627b261fa85099b9718adeaeca096a515db94cf31076a495aa4caa091ecb890c987a0c1f41822e2c14b6b9e6

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,35 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+# Classes here are small enough to explain themselves
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+# Player and PlayerController are cohesive - splitting them would only scatter
+# the state they share
+Metrics/ClassLength:
+  Max: 130
+
+# describe blocks are long by nature
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.6

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in segue.gemspec
+gemspec
+
+gem "rake"
+gem "rspec"
+gem "rubocop"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mark Ryall
+
+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,105 @@
+# Segue
+
+A crossfading queueing daemon for [mpv](https://mpv.io) - kind of like `mpd` but nowhere near as flexible or
+useful.
+
+A *segue* is the radio and DJ term for a transition where one track fades into the next, which is the whole
+point of this thing.
+
+The player daemon starts two instances of mpv and uses those to play any tracks placed in the queue.
+
+Why two instances? mpv doesn't support crossfading between tracks, so this crossfades by starting the other
+mpv instance playing the next track and adjusting the volume of both.
+
+This is a rewrite of [vlcraptor](https://github.com/markryall/vlcraptor), which did the same thing with two
+copies of the VLC desktop app. mpv is a better fit: it's a headless binary rather than a `.app` bundle, it
+speaks JSON over a unix socket instead of a line oriented telnet interface, and it runs anywhere rather than
+only where VLC happens to be installed in `/Applications`.
+
+## Installation
+
+`brew install mpv` (or your platform's equivalent) - segue looks for `mpv` on your `PATH`.
+
+`brew install ffmpeg` is required by the `queue` command for extracting tags to place in the queue.
+
+`brew install terminal-notifier` is optional depending on whether you want notifications when new tracks
+start.
+
+This gem can be installed with `gem install segue`.
+
+## Usage
+
+Running `segue` without any parameters will list the available subcommands.
+
+### Player
+
+Run `segue player` in a shell session.
+
+This is the player daemon that controls two instances of mpv. It is an ncurses application which will take
+over the display in that terminal.
+
+You can quit with 'q', pause with ' ', stop with 's', play (resume) with 'p' and skip with 'n'.
+
+### Adding tracks to the queue
+
+`segue queue folder_containing_audio_files audio_file.mp3` will place any number of audio files in the queue
+and the player should immediately start playing the first track.
+
+### Viewing queue contents
+
+`segue list` will list currently queued tracks with an estimated start time if the player is currently running
+and playing a track.
+
+### Managing queue
+
+`segue clear` will clear all queued tracks.
+
+`segue remove 2` will remove the queued track at index position 2.
+
+`segue swap 2 4` will swap the tracks at index positions 2 and 4.
+
+### Media controls
+
+`segue pause` will pause, `segue stop` will stop and `segue play` will resume.
+
+`segue skip` will fade out the current track and start the next one (unless the queue is empty).
+
+### Optional features
+
+A number of features can be turned on/off while the player is running that will determine certain behaviour:
+
+`segue autoplay off` will cause the player to stop and politely wait after the current track has finished.
+`segue autoplay on` and tracks will start playing again.
+
+`segue crossfade off` will turn off crossfading so new tracks will start once the previous one is completely
+finished.
+
+`segue scrobble on` will turn on last.fm scrobbling - you will require your own application api key and secret
+to enable this.
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SEGUE_HOME` | `~/.segue` | Where preferences, history and the queue are kept |
+| `SEGUE_MPV` | `mpv` | The mpv executable to launch |
+
+Keeping all state under one directory means segue can be run alongside vlcraptor (or a second copy of itself,
+with a different `SEGUE_HOME`) without the two fighting over the same queue.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+The mpv IPC client is covered by specs that talk to a fake mpv over a unix socket, so the test suite does not
+require mpv to be installed.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update
+the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for
+the version, push git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/markryall/segue.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "segue"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/segue

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require "segue"
+
+command = ARGV.shift
+
+case command
+when "autoplay"
+  Segue.autoplay(ARGV.shift)
+when "clear"
+  Segue.clear
+when "crossfade"
+  Segue.crossfade(ARGV.shift)
+when "history"
+  Segue.history
+when "list"
+  Segue.list
+when "pause"
+  Segue.pause
+when "play"
+  Segue.play
+when "player"
+  Segue.player
+when "remove"
+  Segue.remove(ARGV.shift)
+when "queue"
+  Segue.queue(ARGV)
+when "scrobble"
+  Segue.scrobble(ARGV.shift)
+when "skip"
+  Segue.skip
+when "stop"
+  Segue.stop
+when "swap"
+  Segue.swap(ARGV)
+when "version"
+  puts Segue::VERSION
+else
+  puts "Unknown command \"#{command}\":"
+  puts "  autoplay on/off: continue playing tracks or stop at the end of current track"
+  puts "  clear: clear queue"
+  puts "  crossfade on/off: 5 second crossfade when changing tracks"
+  puts "  history: display play history"
+  puts "  list: list current queue"
+  puts "  pause: pause current track (resume with play)"
+  puts "  play: resume after pause/stop"
+  puts "  player: start the player"
+  puts "  queue paths: queue folders or files containing music tracks"
+  puts "  remove a: remove track from queue at index position a"
+  puts "  scrobble on/off: send track information to last.fm (requires an api key)"
+  puts "  skip: skip the current track"
+  puts "  stop: stop the player (resume with play)"
+  puts "  swap a b: swap tracks in queue at index positions a and b"
+  puts "  version: print the segue version"
+end

data/lib/segue/ffmpeg.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Segue
+  # Pulls tags out of a file by parsing what ffmpeg prints about it.
+  class Ffmpeg
+    attr_reader(
+      :title,
+      :album,
+      :artist,
+      :albumartist,
+      :time,
+      :date,
+      :track,
+      :puid,
+      :mbartistid,
+      :mbalbumid,
+      :mbalbumartistid,
+      :asin
+    )
+
+    def initialize(path)
+      @path = path
+      parse
+
+      @title = tag :title, :tit2
+      @album = tag :album, :talb
+      @artist = tag :artist, :tpe1, :tpe2
+      @albumartist = tag :album_artist, :tso2
+      @time = to_duration tag :duration
+      @date = tag :date, :tdrc, :tyer
+      @track = tag :track, :trck
+      @puid = tag :"musicip puid"
+      @mbartistid = tag :musicbrainz_artistid, :"musicbrainz artist id"
+      @mbalbumid = tag :musicbrainz_albumid, :"musicbrainz album id"
+      @mbalbumartistid = tag :musicbrainz_albumartistid, :"musicbrainz album artist id"
+      @asin = tag :asin
+    end
+
+    def tag(*names)
+      names.each { |name| return @meta[name] if @meta[name] }
+      nil
+    end
+
+    private
+
+    def parse
+      @meta = {}
+      collecting = false
+      `ffmpeg -i #{Shellwords.escape(@path)} 2>&1`.each_line do |line|
+        if line.chomp == "  Metadata:"
+          collecting = true
+          next
+        end
+        next unless collecting
+
+        match = / *: */.match line.chomp
+        add_meta match.pre_match.strip.downcase.to_sym, match.post_match.strip if match
+      end
+    end
+
+    def add_meta(key, value)
+      @meta[key] ||= value
+    end
+
+    def to_duration(string)
+      return nil unless string
+
+      first, = string.split ","
+      hours, minutes, seconds = first.split ":"
+      seconds.to_i + (minutes.to_i * 60) + (hours.to_i * 60 * 60)
+    end
+  end
+end

data/lib/segue/mpv.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+module Segue
+  # Client for mpv's JSON IPC protocol.
+  #
+  # mpv speaks newline delimited JSON over a unix socket. Requests carry a
+  # request_id and replies echo it back, which is what lets us ignore the
+  # asynchronous event messages mpv interleaves with responses.
+  class Mpv
+    class Error < RuntimeError
+    end
+
+    CONNECT_TIMEOUT = 5
+    LOAD_TIMEOUT = 5
+    POLL_INTERVAL = 0.05
+
+    attr_reader :socket_path
+
+    def initialize(socket_path)
+      @socket_path = socket_path
+      @request_id = 0
+    end
+
+    # mpv creates the socket a moment after it starts, so retry until it shows up.
+    def connect(timeout: CONNECT_TIMEOUT)
+      deadline = Time.now + timeout
+      begin
+        @socket = UNIXSocket.new(socket_path)
+      rescue Errno::ENOENT, Errno::ECONNREFUSED
+        raise Error, "timed out waiting for mpv socket at #{socket_path}" if Time.now > deadline
+
+        sleep POLL_INTERVAL
+        retry
+      end
+      self
+    end
+
+    def connected?
+      !@socket.nil?
+    end
+
+    def command(*args)
+      reply = request(args)
+      raise Error, "#{args.first}: #{reply["error"]}" unless reply["error"] == "success"
+
+      reply["data"]
+    end
+
+    # Returns nil when mpv considers a property unavailable - time-pos and
+    # duration are both unavailable whenever nothing is loaded.
+    def get(property)
+      request(["get_property", property])["data"]
+    end
+
+    def set(property, value)
+      command("set_property", property, value)
+    end
+
+    def load(path, start: nil)
+      command("loadfile", path, "replace")
+      wait_for_load
+      command("seek", start, "absolute") if start&.positive?
+    end
+
+    def close
+      return unless @socket
+
+      begin
+        request(["quit"])
+      rescue Error, IOError, SystemCallError
+        # mpv may have gone already - nothing left to ask politely
+      end
+      @socket.close unless @socket.closed?
+      @socket = nil
+    end
+
+    private
+
+    def wait_for_load(timeout: LOAD_TIMEOUT)
+      deadline = Time.now + timeout
+      sleep POLL_INTERVAL while get("time-pos").nil? && Time.now < deadline
+    end
+
+    def request(args)
+      raise Error, "not connected to #{socket_path}" unless @socket
+
+      @request_id += 1
+      @socket.puts JSON.generate(command: args, request_id: @request_id)
+      read_reply(@request_id)
+    end
+
+    def read_reply(id)
+      loop do
+        line = @socket.gets
+        raise Error, "mpv closed the connection" if line.nil?
+
+        message = parse(line)
+        return message if message && message["request_id"] == id
+      end
+    end
+
+    def parse(line)
+      JSON.parse(line)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/segue/notifiers.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "rainbow"
+require "shellwords"
+require_relative "paths"
+require_relative "preferences"
+require_relative "scrobbler"
+
+module Segue
+  class Notifiers
+    def initialize
+      @preferences = Segue::Preferences.new
+      @history = Segue::Paths.history
+    end
+
+    def track_suspended
+      @preferences[:started] = nil
+    end
+
+    def track_resumed(track, elapsed)
+      return unless track
+
+      track[:start_time] = Time.now - elapsed
+      @preferences[:started] = track[:start_time].to_i
+    end
+
+    def track_started(track)
+      return unless track
+
+      track[:start_time] = Time.now
+      @preferences[:started] = track[:start_time].to_i
+      scrobbler&.now_playing(track[:artist], track[:title])
+      terminal_notify(
+        message: "#{track[:title]} by #{track[:artist]}",
+        title: "Now Playing"
+      )
+
+      File.open(@history, "a") { |file| file.puts history_line(track) }
+    end
+
+    def track_finished(track)
+      @preferences[:started] = nil
+
+      return unless track
+
+      scrobbler&.scrobble(track[:artist], track[:title], timestamp: track[:start_time].to_i)
+    end
+
+    private
+
+    def history_line(track)
+      [
+        display_time(track[:start_time]),
+        Rainbow(track[:title]).green,
+        "by",
+        Rainbow(track[:artist]).yellow,
+        "from",
+        Rainbow(track[:album]).cyan,
+        "(#{duration(track[:length])})"
+      ].join(" ")
+    end
+
+    def duration(seconds)
+      seconds = seconds.to_i
+      seconds > 60 ? "#{seconds / 60}m and #{seconds % 60}s" : "#{seconds}s"
+    end
+
+    def display_time(time)
+      time.strftime("%I:%M:%S")
+    end
+
+    def terminal_notify(message:, title:)
+      return if `which terminal-notifier`.empty?
+
+      `terminal-notifier -group segue -message #{Shellwords.escape(message)} -title #{Shellwords.escape(title)}`
+    end
+
+    def scrobbler
+      Segue::Scrobbler.load if @preferences.scrobble?
+    end
+  end
+end

data/lib/segue/paths.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Segue
+  # Everything segue writes to disk lives under a single directory so that it
+  # can run alongside other players without fighting over state.
+  module Paths
+    module_function
+
+    def home
+      File.expand_path(ENV.fetch("SEGUE_HOME", "~/.segue")).tap do |path|
+        FileUtils.mkdir_p path
+      end
+    end
+
+    def preferences
+      File.join(home, "preferences.yml")
+    end
+
+    def history
+      File.join(home, "history")
+    end
+
+    def queue
+      File.join(home, "queue").tap { |path| FileUtils.mkdir_p path }
+    end
+
+    # Sockets are scoped to the running player so a crashed one can't leave a
+    # stale path behind that the next player would try to talk to.
+    def socket(name)
+      File.join(Dir.tmpdir, "segue-#{name}-#{Process.pid}.sock")
+    end
+  end
+end