musica 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58e294915c0927510c3ad251196cfa53a23dfe60f1abc87b46688794ae9a8112
-  data.tar.gz: bd8603849d076e7e72d6c3bd47f96b1019d98fd1bc275125c8869993f7bda80c
+  metadata.gz: 68997c53cdcb8c578599e7ede93568d15db73adf953c7c6d674e382aed778ee5
+  data.tar.gz: f5591c92f6bae98c446a2a8bce0be35f6c18749475fe9f553a8fdd79d36c779a
 SHA512:
-  metadata.gz: 3a7913af3724481bec22fc8327dfa475eb5fec30cb9dd18bde95be873033fe388286a9ae6413689a09e5f7549f43e58cfc025e9f6f19854103b1647ef0b369e8
-  data.tar.gz: be741c3b07d5860b22905c6eb30fe4ce843ba93861c291ebfa137cee0b1b879b59a58daefba01b3e0287e1ef4e299ad115bcd8ae6494aeccf5db668a046ef023
+  metadata.gz: 7945760f5d031faf50a9dd0b0161a2b26e5c127214a78c0b15cefeb58d165980640bd7c52d91a02f98d7f71906748d65143e39fb094a2678d4c5c582bbd0b736
+  data.tar.gz: 4ba20cab7bb5ac547b172936eabf69b6d154b6a450faaa3da4f0f57fe7f6eed95f9e11d9bf849dea6eb95b8bd62913dd5b25e8533f0bb44355b0d7360b6c149c

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.3.0] - 2026-10-19
+
+- Turn plain requests into commands by default, without `-n`
+- Send AppleScript commands as is with `-s`/`--script`, which was the default before
+- Add `-h`/`--help` and `-v`/`--version`
+
+## [0.2.0] - 2026-10-19
+
+- Add natural language commands with `-n`, using Apple's on-device model through `fm`
+- Play tracks and albums from the Music library by name, artist or album
+
 ## [0.1.2] - 2025-09-01
 
 - Add YAML configuration support for player selection

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    musica (0.1.2)
+    musica (0.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -14,17 +14,20 @@ GEM
     io-console (0.6.0)
     irb (1.6.3)
       reline (>= 0.3.0)
-    json (2.6.3)
+    json (3.1.0)
     language_server-protocol (3.17.0.3)
+    lint_roller (1.1.0)
     parallel (1.22.1)
-    parser (3.2.1.1)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.7.0)
+    rake (13.4.2)
+    regexp_parser (2.13.1)
     reline (0.3.3)
       io-console (~> 0.5)
-    rexml (3.2.5)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -38,31 +41,43 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.0)
-    rubocop (1.48.1)
-      json (~> 2.3)
-      parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+    rubocop (1.91.0)
+      json (>= 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.26.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.28.0)
-      parser (>= 3.2.1.0)
-    rubocop-performance (1.16.0)
-      rubocop (>= 1.7.0, < 2.0)
-      rubocop-ast (>= 0.4.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
-    standard (1.25.3)
+    standard (1.57.0)
       language_server-protocol (~> 3.17.0.2)
-      rubocop (~> 1.48.1)
-      rubocop-performance (~> 1.16.0)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.91.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
     unicode-display_width (2.4.2)
 
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-25
+  arm64-darwin-27
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -3,11 +3,6 @@
 This is a Ruby command-line tool that interacts with music players on macOS
 using AppleScript.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be
-able to package up your Ruby library into a gem. Put your Ruby code in the file
-`lib/musica`. To experiment with that code, run `bin/console` for an interactive
-prompt.
-
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -20,11 +15,49 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-Run commands to control your music player:
+Tell Musica what you want in plain words:
+
+    $ musica skip this song
+    $ musica turn it down a bit
+    $ musica play Digital Love by Daft Punk
+    $ musica play something by Queen
+    $ musica play the album Adore
+
+Musica uses Apple's on-device model, through the `fm` command, to turn the
+request into a command for your music player. This needs macOS 26 with Apple
+Intelligence.
+
+It understands play, pause, next and previous track, volume changes, and
+playing a track or album from your library by name, artist or album. To play
+an album in order, Musica fills a playlist named "Musica" with its tracks and
+plays that playlist, replacing what was in it before. Playing from your library
+only works with Music.
+
+After each request, Musica prints the current status: the artist and track
+while playing, otherwise the player state:
 
     $ musica play
+    🎧 Daft Punk - Digital Love
     $ musica pause
-    $ musica next track
+    🎧 paused
+
+Run `musica` without arguments to print the status alone, `musica --help` for
+a summary of the options, and `musica --version` for the version.
+
+### AppleScript
+
+With `-s` (or `--script`), Musica sends its arguments to the player as an
+AppleScript command, without `fm`. Any command in the player's AppleScript
+dictionary works (open it in Script Editor with File > Open Dictionary):
+
+    $ musica -s playpause
+    $ musica -s set sound volume to 50
+
+Commands can differ between players. For example, Music uses
+`set shuffle enabled to true` and Spotify uses `set shuffling to true`. Wrap
+commands that contain quotes in single quotes so the shell keeps them:
+
+    $ musica -s 'play playlist "Favorite Songs"'
 
 ## Configuration
 

data/exe/musica

@@ -3,4 +3,8 @@
 require "bundler/setup"
 require "musica"
 
-Musica::Cli.new(ARGV).run
+begin
+  Musica::Cli.new(ARGV).run
+rescue Musica::Error => e
+  abort e.message
+end

data/lib/musica/cli.rb

@@ -1,41 +1,62 @@
 # frozen_string_literal: true
 
-require "yaml"
-require "fileutils"
-
 module Musica
   class Cli
-    def initialize(argv)
-      @prompt = argv.join(" ")
-      @player = Musica::Player.new(application: load_config)
+    HELP = <<~TEXT
+      Usage: musica [request]
+             musica -s <applescript>
+
+      Without arguments, print what's playing. With a request, turn it into a
+      command using fm, send it to the music player, then print what's playing.
+
+      Options:
+        -s, --script   Send an AppleScript command to the player as is
+        -h, --help     Show this help
+        -v, --version  Show the version
+
+      Examples:
+        musica skip this song
+        musica play the album Adore
+        musica -s set sound volume to 50
+
+      The player is set in musica/config.yml, under $XDG_CONFIG_HOME or ~/.config.
+    TEXT
+
+    def initialize(argv, player: nil, interpreter: nil, out: $stdout)
+      @argv = argv
+      @player = player
+      @interpreter = interpreter
+      @out = out
     end
 
     def run
-      player.tell prompt unless prompt.empty?
-      $stdout << "\u{1F3A7} #{player.status}\n"
+      case argv.first
+      when "-h", "--help"
+        out << HELP
+      when "-v", "--version"
+        out << "musica #{VERSION}\n"
+      when "-s", "--script"
+        play argv.drop(1).join(" ")
+      else
+        play(argv.empty? ? "" : interpreter.call(argv.join(" ")))
+      end
     end
 
     private
 
-    attr_reader :argv, :player, :prompt
+    attr_reader :argv, :out
 
-    def load_config
-      config_dir = "#{ENV["XDG_CONFIG_HOME"]}/musica" || File.expand_path("~/.config/musica")
-      config_file = File.join(config_dir, "config.yml")
-
-      unless File.exist?(config_file)
-        create_config(config_dir, config_file)
-      end
-
-      YAML.load_file(config_file).dig("player")
+    def play(command)
+      player.tell command unless command.empty?
+      out << "\u{1F3A7} #{player.status}\n"
     end
 
-    def create_config(config_dir, config_file)
-      FileUtils.mkdir_p(config_dir)
-
-      default_config = { "player" => "Music" }
+    def player
+      @player ||= Player.new(application: Config.player)
+    end
 
-      File.write(config_file, YAML.dump(default_config))
+    def interpreter
+      @interpreter ||= Interpreter.new
     end
   end
 end

data/lib/musica/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Musica
+  module Config
+    DEFAULTS = {"player" => "Music"}.freeze
+
+    def self.player(env: ENV)
+      file = path(env)
+
+      unless File.exist?(file)
+        FileUtils.mkdir_p(File.dirname(file))
+        File.write(file, YAML.dump(DEFAULTS))
+      end
+
+      (YAML.load_file(file) || {}).fetch("player", DEFAULTS["player"])
+    end
+
+    def self.path(env)
+      base = env["XDG_CONFIG_HOME"]
+      base = File.join(env.fetch("HOME"), ".config") if base.nil? || base.empty?
+
+      File.join(base, "musica", "config.yml")
+    end
+    private_class_method :path
+  end
+end

data/lib/musica/intent.json

@@ -0,0 +1,47 @@
+{
+  "title": "Intent",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "action"
+  ],
+  "properties": {
+    "action": {
+      "type": "string",
+      "enum": [
+        "play",
+        "pause",
+        "next_track",
+        "previous_track",
+        "change_volume",
+        "play_track",
+        "play_album",
+        "unknown"
+      ],
+      "description": "What to do"
+    },
+    "name": {
+      "type": "string",
+      "description": "Track name, for play_track"
+    },
+    "artist": {
+      "type": "string",
+      "description": "Artist name, for play_track or play_album"
+    },
+    "album": {
+      "type": "string",
+      "description": "Album name, for play_album"
+    },
+    "delta": {
+      "type": "integer",
+      "description": "Volume change from -100 to 100, for change_volume"
+    }
+  },
+  "x-order": [
+    "action",
+    "name",
+    "artist",
+    "album",
+    "delta"
+  ]
+}

data/lib/musica/interpreter.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Musica
+  class Interpreter
+    SCHEMA = File.expand_path("intent.json", __dir__)
+
+    INSTRUCTIONS = <<~TEXT
+      You turn a request to a music player into an action.
+      - play: resume playback
+      - pause: pause or stop playback
+      - next_track: skip to the next song ("next", "skip")
+      - previous_track: go back to the previous song
+      - change_volume: louder or quieter; delta is the change, 10 for a bit, 30 for a lot, negative for quieter
+      - play_track: play a specific song; name is the song title, artist only if the request names one
+      - play_album: play an album; album is the album title, artist only if the request names one
+      - unknown: anything else
+    TEXT
+
+    FM = lambda do |request|
+      output, status = Open3.capture2(
+        "fm", "respond", "--no-stream", "--greedy",
+        "--schema", SCHEMA, "--instructions", INSTRUCTIONS, request
+      )
+      raise Error, "fm failed to interpret \"#{request}\"" unless status.success?
+
+      output
+    rescue Errno::ENOENT
+      raise Error, "Requests need fm (macOS 26 with Apple Intelligence); use -s to send AppleScript instead"
+    end
+
+    COMMANDS = {
+      "play" => "play",
+      "pause" => "pause",
+      "next_track" => "next track",
+      "previous_track" => "previous track"
+    }.freeze
+
+    # Music can't play an album or queue tracks, so refill a playlist with the
+    # album in disc and track order and play that instead
+    ALBUM = <<~APPLESCRIPT
+      set found to every track of library playlist 1 whose %<conditions>s
+      if found is {} then error "No album " & %<album>s & " in your library"
+      set positions to {}
+      repeat with t in found
+        set end of positions to (disc number of t) * 1000 + (track number of t)
+      end repeat
+      if not (exists user playlist "Musica") then make new user playlist with properties {name:"Musica"}
+      set musica to user playlist "Musica"
+      delete every track of musica
+      repeat (count of found) times
+        set best to 0
+        repeat with i from 1 to count of found
+          if item i of positions is not missing value then
+            if best is 0 or item i of positions < item best of positions then set best to i
+          end if
+        end repeat
+        duplicate item best of found to musica
+        set item best of positions to missing value
+      end repeat
+      play musica
+    APPLESCRIPT
+
+    def initialize(runner: FM)
+      @runner = runner
+    end
+
+    def call(request)
+      intent = JSON.parse(runner.call(request))
+      name = mentioned(intent["name"], request)
+      artist = mentioned(intent["artist"], request)
+      album = mentioned(intent["album"], request)
+
+      case intent["action"]
+      when "play", "play_track", "play_album"
+        if album && !name
+          play_album(album, artist)
+        elsif name || artist
+          play_track(name, artist, album)
+        else
+          "play"
+        end
+      when "change_volume"
+        volume(intent["delta"], request)
+      else
+        COMMANDS.fetch(intent["action"]) { not_understood(request) }
+      end
+    end
+
+    private
+
+    attr_reader :runner
+
+    def mentioned(value, request)
+      value if value.is_a?(String) && !value.empty? && request.downcase.include?(value.downcase)
+    end
+
+    def play_track(name, artist, album)
+      "play (some track of library playlist 1 whose #{conditions("name" => name, "artist" => artist, "album" => album)})"
+    end
+
+    def play_album(album, artist)
+      format(ALBUM, conditions: conditions("album" => album, "artist" => artist), album: quote(album))
+    end
+
+    def conditions(filters)
+      filters.compact.map { |key, value| "#{key} is #{quote(value)}" }.join(" and ")
+    end
+
+    def volume(delta, request)
+      not_understood(request) unless delta.is_a?(Integer)
+
+      "set sound volume to (sound volume + #{delta})"
+    end
+
+    def quote(value)
+      %("#{value.gsub(/[\\"]/) { |char| "\\#{char}" }}")
+    end
+
+    def not_understood(request)
+      raise Error, "Couldn't understand \"#{request}\""
+    end
+  end
+end

data/lib/musica/player.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
+require "open3"
+
 module Musica
   class Player
-    def initialize(application:)
+    OSASCRIPT = ->(script) { Open3.capture2("osascript", "-e", script).first.chomp }
+
+    def initialize(application:, runner: OSASCRIPT)
       @application = application
+      @runner = runner
     end
 
     def status
@@ -11,12 +16,12 @@ module Musica
     end
 
     def tell(command)
-      `osascript -e 'tell application "#{application}" to #{command}'`.chomp
+      runner.call(%(tell application "#{application}"\n#{command}\nend tell))
     end
 
     private
 
-    attr_reader :application
+    attr_reader :application, :runner
 
     def artist
       tell "return artist of the current track"

data/lib/musica/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Musica
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/musica.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "musica/cli"
+require_relative "musica/config"
+require_relative "musica/interpreter"
 require_relative "musica/player"
 require_relative "musica/version"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: musica
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Ariel Rzezak
@@ -28,6 +28,9 @@ files:
 - exe/musica
 - lib/musica.rb
 - lib/musica/cli.rb
+- lib/musica/config.rb
+- lib/musica/intent.json
+- lib/musica/interpreter.rb
 - lib/musica/player.rb
 - lib/musica/version.rb
 - sig/musica.rbs
@@ -52,7 +55,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.23
 specification_version: 4
 summary: Control macOS music players from the command-line
 test_files: []