rocksky 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84425f844d397e7187168e44115168f310f5a48269da6b1f3efc424cbf9991aa
-  data.tar.gz: 89e6d0d11fd1f88ec4e80498251f1d1d24cc4e77587860b7c96b0508306a3817
+  metadata.gz: 411359937d7cc586384c4b58c7e32f4824cc4cfb1ee0e3ec3f38c0071b0b3b30
+  data.tar.gz: 97525f3e9c77f00c136a9f349f18747965dba4aa02f4e55bb1fb6587d926fc6f
 SHA512:
-  metadata.gz: b48c2675d3ecedc52f6b2c7b70a728d927dd69a2564bfe16bc8b55101dfbf866e44b67957b1ad866c57819b0b66360aa637745a73c87238b0c769aa5b5b5e49a
-  data.tar.gz: bbc58f41ea90eda2c8878cde5e6c182a364a5d8de5f4056ab5e6baad5178c67756cf2f02da5343a2b1a679d83839c02b0c1787de64ec6119a42c979abc9a9e2a
+  metadata.gz: 49ce584a23a45ecab4725b82308b6968468e2e3104267d4e5ca6696241d149ce224872d8eb303b8dd7680c2e4bc97e738feac641760dfb05c7d5330ef527d5e8
+  data.tar.gz: 4cc152d4c19bfaa289a7422426abe6878d2fae69fda3f0063846b3ece0080c979f9d2b4077415f650bd34d4e7b466d13d3bac045c4e5c94a5e5495034253eee8

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.11.0
+
+- Added `Rocksky::Filter`, a fluent RSQL builder (`eq`, `ne`, `gt`, `ge`,
+  `lt`, `le`, `is_in`, `is_out`, `is_null`, `is_not_null`, combined with
+  `#and` / `#or`). Fields are Symbols (`:artist`, `:"track.artist"`); values
+  are quoted/escaped automatically, `*` wildcards stay bare.
+- Added filterable reads: `Rocksky.catalog_songs`, `catalog_artists`,
+  `catalog_albums` (`limit:`, `offset:`, `genre:`, `filter:`) and
+  `Rocksky.scrobble_feed` (`did:`, `following:`, `limit:`, `offset:`,
+  `filter:`). `filter:` takes a `Rocksky::Filter` or a raw RSQL String.
+
+## 0.10.0
+
+- Remote-player protocol: now-playing records accept optional audio info —
+  `codec` (audio codec/container, e.g. "mp3", "flac") and `sampleRate` (sample
+  rate in Hz, e.g. 44100). A player includes them in the `track` payload when
+  set (`codec` / `sample_rate` on the wire, omitted otherwise); a controller's
+  `:now_playing` event exposes them on the `:track` hash.
+
 ## 0.9.1
 
 - Fix a segfault when tearing down a `RemotePlayer` / `RemoteController`.

data/README.md

@@ -14,7 +14,7 @@ gem install rocksky
 Or in a Gemfile:
 
 ```ruby
-gem "rocksky", "~> 0.7"
+gem "rocksky", "~> 0.11"
 ```
 
 The gem is pure-Ruby; the native library is fetched from the GitHub release on
@@ -83,6 +83,31 @@ Rocksky.top_artists_interval(limit: 5, interval: :all)
 **Match** — `Rocksky.match_song(title, artist, mb_id: nil, isrc: nil)` resolves a
 bare title + artist into full canonical metadata.
 
+### Filtering
+
+`Rocksky::Filter` builds RSQL expressions for the `filter:` kwarg of
+`catalog_songs`, `catalog_artists`, `catalog_albums` and `scrobble_feed`
+(each also takes `limit:`, `offset:` and — catalogs only — `genre:`). Fields
+are Symbols; dotted selectors on the scrobble feed reach the joined
+track/user/artist (`:"track.artist"`, `:"user.handle"`, …).
+
+```ruby
+filter = Rocksky::Filter.eq(:artist, "Daft Punk")
+                        .and(Rocksky::Filter.gt(:duration, 200_000))
+                        .or(Rocksky::Filter.is_in(:genre, %w[house electro]))
+filter.to_s # => artist=="Daft Punk";duration=gt=200000,genre=in=(house,electro)
+
+Rocksky.catalog_songs(limit: 20, filter: filter)
+Rocksky.scrobble_feed(filter: Rocksky::Filter.eq(:"track.artist", "Daft Punk"))
+```
+
+Constructors: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `is_in`, `is_out` (aliases
+`in`/`out`), `is_null`, `is_not_null`. Combine with `#and` (`;`) and `#or`
+(`,`); an OR operand inside an AND is parenthesized automatically. String
+values are quoted/escaped when they contain reserved characters, and `*`
+wildcards pass through unquoted (`Filter.eq(:artist, "Daft*")`). A raw RSQL
+String is accepted anywhere a `Filter` is.
+
 ### Writes — `Rocksky::Agent`
 
 `Agent.login(session_path, identifier, password, appview:, dedup_path:)` → an

data/lib/rocksky/filter.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Standalone — no native core involved. Loads on its own via
+# `require "rocksky/filter"`.
+module Rocksky
+  # Fluent builder for RSQL filter expressions, accepted by the +filter:+
+  # parameter of the catalog and scrobble-feed queries
+  # (app.rocksky.song.getSongs, app.rocksky.artist.getArtists,
+  # app.rocksky.album.getAlbums, app.rocksky.scrobble.getScrobbles).
+  #
+  #     require "rocksky"
+  #
+  #     filter = Rocksky::Filter.eq(:artist, "Daft Punk")
+  #                             .and(Rocksky::Filter.gt(:duration, 200_000))
+  #                             .or(Rocksky::Filter.is_in(:genre, %w[house electro]))
+  #
+  #     Rocksky.catalog_songs(filter: filter)
+  #     # artist=="Daft Punk";duration=gt=200000,genre=in=(house,electro)
+  #
+  # Fields are Symbols (Strings work too); dotted selectors on the scrobble
+  # feed are written as +:"track.artist"+. String values are quoted and
+  # escaped automatically when they contain characters RSQL reserves; +*+
+  # wildcards pass through unquoted so <tt>Filter.eq(:artist, "Daft*")</tt>
+  # performs a case-insensitive match.
+  class Filter
+    # Characters that never need quoting in an RSQL value (+*+ kept bare so
+    # wildcards work).
+    SAFE_VALUE = /\A[A-Za-z0-9_.:@*+-]+\z/
+    private_constant :SAFE_VALUE
+
+    class << self
+      # +field==value+ — equals; +*+ in string values is a wildcard.
+      def eq(field, value)
+        comparison(field, "==", value)
+      end
+
+      # +field!=value+ — not equals.
+      def ne(field, value)
+        comparison(field, "!=", value)
+      end
+
+      # +field=gt=value+ — greater than.
+      def gt(field, value)
+        comparison(field, "=gt=", value)
+      end
+
+      # +field=ge=value+ — greater than or equal.
+      def ge(field, value)
+        comparison(field, "=ge=", value)
+      end
+
+      # +field=lt=value+ — less than.
+      def lt(field, value)
+        comparison(field, "=lt=", value)
+      end
+
+      # +field=le=value+ — less than or equal.
+      def le(field, value)
+        comparison(field, "=le=", value)
+      end
+
+      # +field=in=(a,b)+ — matches any of the values.
+      def is_in(field, values)
+        list(field, "=in=", values)
+      end
+
+      # +field=out=(a,b)+ — matches none of the values.
+      def is_out(field, values)
+        list(field, "=out=", values)
+      end
+
+      alias in is_in
+      alias out is_out
+
+      # +field==null+ — the field is NULL.
+      def is_null(field)
+        new("#{field}==null", :comparison)
+      end
+
+      # +field!=null+ — the field is not NULL.
+      def is_not_null(field)
+        new("#{field}!=null", :comparison)
+      end
+
+      private
+
+      def comparison(field, op, value)
+        new("#{field}#{op}#{render_value(value)}", :comparison)
+      end
+
+      def list(field, op, values)
+        name = op == "=in=" ? "is_in" : "is_out"
+        raise ArgumentError, "Filter.#{name}(#{field.inspect}, ...) needs at least one value" if values.empty?
+
+        new("#{field}#{op}(#{values.map { |v| render_value(v) }.join(",")})", :comparison)
+      end
+
+      def render_value(value)
+        return value.to_s if value.is_a?(Integer) || value.is_a?(Float) ||
+                             value == true || value == false
+
+        str = value.to_s
+        return str if !str.empty? && SAFE_VALUE.match?(str)
+
+        %("#{str.gsub(/(["\\])/) { "\\#{Regexp.last_match(1)}" }}")
+      end
+    end
+
+    def initialize(expr, kind)
+      @expr = expr
+      @kind = kind
+    end
+
+    # Both sides must match (+;+). An +or+ operand is parenthesized to keep
+    # RSQL precedence.
+    def and(other)
+      Filter.new("#{operand_in_and};#{other.operand_in_and}", :and)
+    end
+
+    # Either side may match (+,+). Never parenthesizes.
+    def or(other)
+      Filter.new("#{@expr},#{other.build}", :or)
+    end
+
+    # The RSQL expression string to send as the +filter+ query param.
+    def build
+      @expr
+    end
+
+    alias to_s build
+
+    protected
+
+    def operand_in_and
+      @kind == :or ? "(#{@expr})" : @expr
+    end
+  end
+end

data/lib/rocksky/manifest.json

@@ -1,12 +1,12 @@
 {
   "repo": "tsirysndr/rocksky",
-  "tag": "bindings-v0.6.0",
+  "tag": "bindings-v0.8.0",
   "checksums": {
-    "aarch64-apple-darwin": "e2de89af96e1330427898524254ddb57728453947b607c4dd29fb8ed7c513b27",
-    "aarch64-linux-gnu": "37b8f5ec3812cb15f7eeb75beb44ffe857cca95c11064d1e781eaff6edf7c14d",
-    "x86_64-apple-darwin": "7a550b51fc75e1e4d7c5393423f2920dda980ea8f026c9bde8edd926d18d3795",
-    "x86_64-linux-gnu": "683e9c14579041c77fa69b53f73b43a44432719c608d7af74f950c9263c5c53b",
-    "x86_64-unknown-freebsd": "4ecf5a61000b46111aef2c66e241c97e712c8ef6af386a01afddfe2c05136893",
-    "x86_64-unknown-netbsd": "0c619e60f6cf95c42bbe61adb26be8550024c8cbea08be6de9fb3127db627900"
+    "aarch64-apple-darwin": "31b58deb0f3d627d37b101f06b5b4a952401040f076b4cea7436aa338080a701",
+    "aarch64-linux-gnu": "dca60c186ee83401e9afcdf1e7b31c308594f6dcda4cab25acf77254739d2a49",
+    "x86_64-apple-darwin": "bdf2c98ddc866280712c928d78d4173c1760deac6d8c567417b90ea20fba1bb4",
+    "x86_64-linux-gnu": "74dede20bb5892eff8ad321721a3f4584227bf2c97d78c2febeec095d2df46b6",
+    "x86_64-unknown-freebsd": "e6af79359f73a9d42d6232eade70f5e3938e75b66bc240e1077d76334daa08fe",
+    "x86_64-unknown-netbsd": "d1765e3c66d99a1160ddb3361ff9cfcf9c1335a056e68d089ea1c97ef6ff3f16"
   }
 }

data/lib/rocksky/remote.rb

@@ -27,7 +27,8 @@ module Rocksky
   #
   # Records (now-playing / queue items) are passed as Hashes with camelCase keys
   # (title, artist, album, albumArtist, albumArt, durationMs, elapsedMs,
-  # isPlaying / songUri, albumUri, trackNumber), matching the wire record shape.
+  # isPlaying, codec, sampleRate / songUri, albumUri, trackNumber), matching the
+  # wire record shape.
   class RemotePlayer
     # Connect and register a controllable player in the background. +token+ is a
     # Rocksky access token (JWT); +name+ is the device-picker label; +url+
@@ -79,7 +80,10 @@ module Rocksky
 
     # Advertise the currently-playing track. Call whenever it changes, and
     # periodically (~every 1–4s) with a fresh +elapsedMs+ so controllers show
-    # smooth progress. +track+ is a camelCase Hash.
+    # smooth progress. +track+ is a camelCase Hash. Optional audio info —
+    # +codec+ (audio codec/container, e.g. "mp3", "flac") and +sampleRate+
+    # (sample rate in Hz, e.g. 44100) — is included in the track payload when
+    # set, and omitted otherwise.
     def set_now_playing(track)
       Rocksky.unwrap(C.rocksky_remote_player_set_now_playing(@ptr, JSON.generate(track)))
     end
@@ -164,7 +168,9 @@ module Rocksky
     # Register a handler for a server event type, one of +:devices+,
     # +:device_registered+, +:device_unregistered+, +:primary_changed+,
     # +:now_playing+, +:status+, +:queue+. The block receives the full
-    # symbol-keyed event Hash. Returns +self+ for chaining.
+    # symbol-keyed event Hash. A +:now_playing+ event carries the advertised
+    # track under +:track+, including optional +:codec+ / +:sampleRate+ audio
+    # info when the player supplied it. Returns +self+ for chaining.
     def on(event_type, &block)
       @handlers[event_type.to_sym] = block
       self

data/lib/rocksky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rocksky
-  VERSION = "0.9.1"
+  VERSION = "0.11.0"
 end

data/lib/rocksky.rb

@@ -127,6 +127,51 @@ module Rocksky
     unwrap(C.rocksky_global_stats(base.to_s))
   end
 
+  # ---- catalog + feed reads with RSQL filtering ----
+  #
+  # +filter:+ accepts a Rocksky::Filter (see rocksky/filter.rb) or a raw RSQL
+  # String. Fields are Symbols, e.g. Rocksky::Filter.eq(:artist, "Daft Punk").
+
+  # The song catalog (app.rocksky.song.getSongs), optionally narrowed by
+  # +genre:+ and/or an RSQL +filter:+. Returns { "tracks" => [...] }.
+  def self.catalog_songs(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.song.getSongs", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # The artist catalog (app.rocksky.artist.getArtists). Returns
+  # { "artists" => [...] }.
+  def self.catalog_artists(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.artist.getArtists", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # The album catalog (app.rocksky.album.getAlbums). Returns
+  # { "albums" => [...] }.
+  def self.catalog_albums(limit: 50, offset: 0, genre: nil, filter: nil, base: nil)
+    get("app.rocksky.album.getAlbums", catalog_params(limit, offset, genre, filter), base: base)
+  end
+
+  # A social/global scrobbles feed (app.rocksky.scrobble.getScrobbles). Pass
+  # +did:+ to scope to an actor and +following: true+ for their follow graph.
+  # +filter:+ reaches the joined track/user/artist via dotted fields, e.g.
+  # Rocksky::Filter.eq(:"track.artist", "Daft Punk"). Returns
+  # { "scrobbles" => [...] }.
+  def self.scrobble_feed(did: nil, following: false, limit: 50, offset: 0, filter: nil, base: nil)
+    params = { limit: limit, offset: offset }
+    params[:did] = did unless did.nil?
+    params[:following] = following if following
+    params[:filter] = filter.to_s unless filter.nil?
+    get("app.rocksky.scrobble.getScrobbles", params, base: base)
+  end
+
+  # Shared param assembly for the three catalog reads (omit-nil idiom).
+  def self.catalog_params(limit, offset, genre, filter)
+    params = { limit: limit, offset: offset }
+    params[:genre] = genre unless genre.nil?
+    params[:filter] = filter.to_s unless filter.nil?
+    params
+  end
+  private_class_method :catalog_params
+
   # Universal read escape hatch — call any app.rocksky.* query by nsid. +params+
   # is a hash of string params; the whole read-query catalog is reachable here.
   #
@@ -301,5 +346,6 @@ module Rocksky
   end
 end
 
+require_relative "rocksky/filter"
 require_relative "rocksky/library"
 require_relative "rocksky/remote"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rocksky
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Rocksky
@@ -80,6 +80,7 @@ files:
 - README.md
 - exe/rocksky-console
 - lib/rocksky.rb
+- lib/rocksky/filter.rb
 - lib/rocksky/library.rb
 - lib/rocksky/manifest.json
 - lib/rocksky/native.rb