rockbox 0.1.0

data/lib/rockbox/api/settings.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module Rockbox
+  module Api
+    class Settings
+      QUERY = <<~GQL
+        query GlobalSettings {
+          globalSettings {
+            musicDir volume balance bass treble channelConfig stereoWidth
+            eqEnabled eqPrecut
+            eqBandSettings { cutoff q gain }
+            replaygainSettings { noclip type preamp }
+            compressorSettings { threshold makeupGain ratio knee releaseTime attackTime }
+            crossfadeEnabled crossfadeFadeInDelay crossfadeFadeInDuration
+            crossfadeFadeOutDelay crossfadeFadeOutDuration crossfadeFadeOutMixmode
+            crossfeedEnabled crossfeedDirectGain crossfeedCrossGain
+            crossfeedHfAttenuation crossfeedHfCutoff
+            repeatMode singleMode partyMode shuffle playerName
+          }
+        }
+      GQL
+
+      def initialize(http)
+        @http = http
+      end
+
+      # @return [Rockbox::UserSettings]
+      def get
+        s = @http.execute(QUERY)[:global_settings] || {}
+
+        UserSettings.new(
+          music_dir:                   s[:music_dir],
+          volume:                      s[:volume],
+          balance:                     s[:balance],
+          bass:                        s[:bass],
+          treble:                      s[:treble],
+          channel_config:              s[:channel_config],
+          stereo_width:                s[:stereo_width],
+          eq_enabled:                  s[:eq_enabled],
+          eq_precut:                   s[:eq_precut],
+          eq_band_settings:            Array(s[:eq_band_settings]).map { |b| EqBandSetting.from_hash(b) },
+          replaygain_settings:         ReplaygainSettings.from_hash(s[:replaygain_settings]),
+          compressor_settings:         CompressorSettings.from_hash(s[:compressor_settings]),
+          crossfade_enabled:           s[:crossfade_enabled],
+          crossfade_fade_in_delay:     s[:crossfade_fade_in_delay],
+          crossfade_fade_in_duration:  s[:crossfade_fade_in_duration],
+          crossfade_fade_out_delay:    s[:crossfade_fade_out_delay],
+          crossfade_fade_out_duration: s[:crossfade_fade_out_duration],
+          crossfade_fade_out_mixmode:  s[:crossfade_fade_out_mixmode],
+          crossfeed_enabled:           s[:crossfeed_enabled],
+          crossfeed_direct_gain:       s[:crossfeed_direct_gain],
+          crossfeed_cross_gain:        s[:crossfeed_cross_gain],
+          crossfeed_hf_attenuation:    s[:crossfeed_hf_attenuation],
+          crossfeed_hf_cutoff:         s[:crossfeed_hf_cutoff],
+          repeat_mode:                 s[:repeat_mode],
+          single_mode:                 s[:single_mode],
+          party_mode:                  s[:party_mode],
+          shuffle:                     s[:shuffle],
+          player_name:                 s[:player_name]
+        )
+      end
+
+      # Save a partial settings update. Pass any subset of keys; everything
+      # else is left as-is by the firmware.
+      #
+      # @example Builder block
+      #   client.settings.save do |s|
+      #     s.volume = -20
+      #     s.bass = 4
+      #     s.shuffle = true
+      #   end
+      #
+      # @example Hash
+      #   client.settings.save(volume: -20, bass: 4)
+      def save(settings = nil, &block)
+        if block
+          builder = SaveBuilder.new
+          yield builder
+          settings = builder.to_h.merge(settings || {})
+        end
+        raise ArgumentError, "settings hash or block required" if settings.nil? || settings.empty?
+
+        @http.execute(
+          "mutation SaveSettings($settings: NewGlobalSettings!) { saveSettings(settings: $settings) }",
+          { settings: settings }
+        )
+        nil
+      end
+
+      class SaveBuilder
+        SETTABLE = %i[
+          music_dir volume balance bass treble channel_config stereo_width
+          eq_enabled eq_precut eq_band_settings replaygain_settings compressor_settings
+          crossfade_enabled crossfade_fade_in_delay crossfade_fade_in_duration
+          crossfade_fade_out_delay crossfade_fade_out_duration crossfade_fade_out_mixmode
+          crossfeed_enabled crossfeed_direct_gain crossfeed_cross_gain
+          crossfeed_hf_attenuation crossfeed_hf_cutoff
+          repeat_mode single_mode party_mode shuffle player_name
+        ].freeze
+
+        def initialize
+          @attrs = {}
+        end
+
+        SETTABLE.each do |attr|
+          define_method("#{attr}=") { |value| @attrs[attr] = value }
+          define_method(attr)        { @attrs[attr] }
+        end
+
+        def to_h
+          @attrs.dup
+        end
+      end
+    end
+  end
+end

data/lib/rockbox/api/smart_playlists.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module Rockbox
+  module Api
+    class SmartPlaylists
+      def initialize(http)
+        @http = http
+      end
+
+      def list
+        data = @http.execute(<<~GQL)
+          query SmartPlaylists {
+            smartPlaylists { id name description image folderId isSystem rules createdAt updatedAt }
+          }
+        GQL
+        Array(data[:smart_playlists]).map { |p| SmartPlaylist.from_hash(p) }
+      end
+
+      def get(id)
+        data = @http.execute(
+          "query SmartPlaylist($id: String!) { " \
+          "smartPlaylist(id: $id) { id name description image folderId isSystem rules createdAt updatedAt } }",
+          { id: id }
+        )
+        SmartPlaylist.from_hash(data[:smart_playlist])
+      end
+
+      def track_ids(id)
+        @http.execute(
+          "query SmartPlaylistTrackIds($id: String!) { smartPlaylistTrackIds(id: $id) }",
+          { id: id }
+        )[:smart_playlist_track_ids] || []
+      end
+
+      # @example
+      #   client.smart_playlists.create(name: "Heavy hitters", rules: rules_json)
+      def create(name:, rules:, description: nil, image: nil, folder_id: nil)
+        vars = { name: name, rules: rules, description: description,
+                 image: image, folder_id: folder_id }.compact
+        data = @http.execute(<<~GQL, vars)
+          mutation CreateSmartPlaylist(
+            $name: String!, $rules: String!, $description: String,
+            $image: String, $folderId: String
+          ) {
+            createSmartPlaylist(
+              name: $name, rules: $rules, description: $description,
+              image: $image, folderId: $folderId
+            ) { id name description image folderId isSystem rules createdAt updatedAt }
+          }
+        GQL
+        SmartPlaylist.from_hash(data[:create_smart_playlist])
+      end
+
+      def update(id, name:, rules:, description: nil, image: nil, folder_id: nil)
+        vars = { id: id, name: name, rules: rules, description: description,
+                 image: image, folder_id: folder_id }.compact
+        @http.execute(<<~GQL, vars)
+          mutation UpdateSmartPlaylist(
+            $id: String!, $name: String!, $rules: String!,
+            $description: String, $image: String, $folderId: String
+          ) {
+            updateSmartPlaylist(
+              id: $id, name: $name, rules: $rules,
+              description: $description, image: $image, folderId: $folderId
+            )
+          }
+        GQL
+        nil
+      end
+
+      def delete(id)
+        @http.execute("mutation DeleteSmartPlaylist($id: String!) { deleteSmartPlaylist(id: $id) }", { id: id })
+        nil
+      end
+
+      def play(id)
+        @http.execute("mutation PlaySmartPlaylist($id: String!) { playSmartPlaylist(id: $id) }", { id: id })
+        nil
+      end
+
+      # ---------------------------------------------------------------------
+      # Listening stats
+      # ---------------------------------------------------------------------
+
+      def track_stats(track_id)
+        data = @http.execute(<<~GQL, { track_id: track_id })
+          query TrackStats($trackId: String!) {
+            trackStats(trackId: $trackId) {
+              trackId playCount skipCount lastPlayed lastSkipped updatedAt
+            }
+          }
+        GQL
+        TrackStats.from_hash(data[:track_stats])
+      end
+
+      def record_played(track_id)
+        @http.execute(
+          "mutation RecordTrackPlayed($trackId: String!) { recordTrackPlayed(trackId: $trackId) }",
+          { track_id: track_id }
+        )
+        nil
+      end
+
+      def record_skipped(track_id)
+        @http.execute(
+          "mutation RecordTrackSkipped($trackId: String!) { recordTrackSkipped(trackId: $trackId) }",
+          { track_id: track_id }
+        )
+        nil
+      end
+    end
+  end
+end

data/lib/rockbox/api/sound.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module Rockbox
+  module Api
+    class Sound
+      def initialize(http)
+        @http = http
+      end
+
+      # @return [Rockbox::VolumeInfo]
+      def volume
+        data = @http.execute("query Volume { volume { volume min max } }")
+        VolumeInfo.from_hash(data[:volume])
+      end
+
+      # Adjust volume by N steps (positive = louder, negative = quieter).
+      # @return [Integer] resulting volume
+      def adjust(steps)
+        @http.execute(
+          "mutation AdjustVolume($steps: Int!) { adjustVolume(steps: $steps) }",
+          { steps: steps }
+        )[:adjust_volume]
+      end
+
+      def up;   adjust(1);  end
+      def down; adjust(-1); end
+    end
+  end
+end

data/lib/rockbox/api/system.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module Rockbox
+  module Api
+    class System
+      def initialize(http)
+        @http = http
+      end
+
+      # @return [String]
+      def version
+        @http.execute("query Version { rockboxVersion }")[:rockbox_version]
+      end
+
+      # @return [Rockbox::SystemStatus]
+      def status
+        data = @http.execute(<<~GQL)
+          query GlobalStatus {
+            globalStatus {
+              resumeIndex resumeCrc32 resumeElapsed resumeOffset
+              runtime topruntime dircacheSize
+              lastScreen viewerIconCount lastVolumeChange
+            }
+          }
+        GQL
+        SystemStatus.from_hash(data[:global_status])
+      end
+    end
+  end
+end

data/lib/rockbox/case_conversion.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Rockbox
+  # Convert between GraphQL camelCase JSON keys and Ruby snake_case symbols.
+  # The transport applies these on every request/response so user code can
+  # always work in idiomatic Ruby.
+  module CaseConversion
+    module_function
+
+    def camelize(str)
+      head, *tail = str.to_s.split("_")
+      ([head] + tail.map(&:capitalize)).join
+    end
+
+    def snakeize(str)
+      str.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    end
+
+    # Recursively rewrite a Hash/Array — used on outgoing variable payloads.
+    def deep_camelize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[camelize(k)] = deep_camelize(v) }
+      when Array
+        obj.map { |v| deep_camelize(v) }
+      else
+        obj
+      end
+    end
+
+    # Recursively rewrite a Hash/Array — used on incoming GraphQL responses.
+    def deep_snakeize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[snakeize(k).to_sym] = deep_snakeize(v) }
+      when Array
+        obj.map { |v| deep_snakeize(v) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/rockbox/client.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "transport"
+require_relative "events"
+require_relative "plugin"
+require_relative "types"
+
+require_relative "api/playback"
+require_relative "api/library"
+require_relative "api/playlist"
+require_relative "api/saved_playlists"
+require_relative "api/smart_playlists"
+require_relative "api/sound"
+require_relative "api/settings"
+require_relative "api/system"
+require_relative "api/browse"
+require_relative "api/devices"
+require_relative "api/bluetooth"
+
+module Rockbox
+  # ---------------------------------------------------------------------------
+  # Rockbox::Client — main entry point.
+  #
+  # Inspired by:
+  #   Mopidy    — domain namespace API (client.playback.play, client.library.search)
+  #   Jellyfin  — plugin install/uninstall lifecycle
+  #   Kodi      — rich device + playlist management
+  #
+  # @example Quick start
+  #   client = Rockbox::Client.new
+  #   client.connect  # start WebSocket subscriptions
+  #
+  #   client.on(:track_changed) { |track| puts "Now playing: #{track.title}" }
+  #
+  #   results = client.library.search("dark side")
+  #   client.playback.play_album(results.albums.first.id, shuffle: true)
+  #
+  # @example Builder DSL
+  #   client = Rockbox::Client.build do |c|
+  #     c.host = "192.168.1.42"
+  #     c.port = 6062
+  #   end
+  # ---------------------------------------------------------------------------
+  class Client
+    attr_reader :playback, :library, :playlist, :saved_playlists, :smart_playlists,
+                :sound, :settings, :system, :browse, :devices, :bluetooth,
+                :configuration
+
+    # Block-form constructor — yields a {Configuration} for tweaking.
+    def self.build
+      config = Configuration.new
+      yield config if block_given?
+      new(configuration: config)
+    end
+
+    # @param host         [String]  hostname or IP of rockboxd (default: "localhost")
+    # @param port         [Integer] GraphQL port (default: 6062)
+    # @param http_url     [String]  override the full HTTP URL
+    # @param ws_url       [String]  override the full WebSocket URL
+    # @param open_timeout [Integer] HTTP connect timeout (seconds)
+    # @param read_timeout [Integer] HTTP read timeout (seconds)
+    # @param configuration [Configuration] pre-built configuration (rare)
+    def initialize(host: nil, port: nil, http_url: nil, ws_url: nil,
+                   open_timeout: nil, read_timeout: nil, configuration: nil)
+      @configuration = configuration || Configuration.new(
+        host: host, port: port,
+        http_url: http_url, ws_url: ws_url,
+        open_timeout: open_timeout, read_timeout: read_timeout
+      )
+
+      @http = HttpTransport.new(
+        @configuration.resolved_http_url,
+        open_timeout: @configuration.open_timeout || HttpTransport::DEFAULT_OPEN_TIMEOUT,
+        read_timeout: @configuration.read_timeout || HttpTransport::DEFAULT_READ_TIMEOUT
+      )
+      @ws = WsTransport.new(@configuration.resolved_ws_url)
+
+      @events = EventEmitter.new
+      @plugins = PluginRegistry.new
+      @subscriptions = []
+
+      @playback        = Api::Playback.new(@http)
+      @library         = Api::Library.new(@http)
+      @playlist        = Api::Playlist.new(@http)
+      @saved_playlists = Api::SavedPlaylists.new(@http)
+      @smart_playlists = Api::SmartPlaylists.new(@http)
+      @sound           = Api::Sound.new(@http)
+      @settings        = Api::Settings.new(@http)
+      @system          = Api::System.new(@http)
+      @browse          = Api::Browse.new(@http)
+      @devices         = Api::Devices.new(@http)
+      @bluetooth       = Api::Bluetooth.new(@http)
+    end
+
+    # ---------------------------------------------------------------------------
+    # Events — block-friendly delegation to the EventEmitter
+    # ---------------------------------------------------------------------------
+
+    def on(event, &block);                     @events.on(event, &block);  self; end
+    def once(event, &block);                   @events.once(event, &block); self; end
+    def off(event, listener = nil, &block);    @events.off(event, listener, &block); self; end
+    def emit(event, payload = nil);            @events.emit(event, payload);  self; end
+    def remove_all_listeners(event = nil);     @events.remove_all_listeners(event); self; end
+
+    # ---------------------------------------------------------------------------
+    # Real-time subscriptions
+    # ---------------------------------------------------------------------------
+
+    # Open the WebSocket and subscribe to the three default streams. Idempotent.
+    #
+    # @return [self]
+    def connect
+      return self unless @subscriptions.empty?
+
+      @subscriptions << @ws.subscribe(
+        <<~GQL, nil,
+          subscription CurrentlyPlaying {
+            currentlyPlayingSong {
+              id title artist album albumArt albumId artistId path length elapsed
+            }
+          }
+        GQL
+        next: ->(result) {
+          payload = result[:data]&.dig(:currently_playing_song)
+          @events.emit(:track_changed, Track.from_hash(payload)) if payload
+        },
+        error: ->(err) { @events.emit(:ws_error, wrap_error(err)) },
+        complete: -> {}
+      )
+
+      @subscriptions << @ws.subscribe(
+        "subscription PlaybackStatus { playbackStatus { status } }", nil,
+        next: ->(result) {
+          status = result[:data]&.dig(:playback_status, :status)
+          @events.emit(:status_changed, status) unless status.nil?
+        },
+        error: ->(err) { @events.emit(:ws_error, wrap_error(err)) },
+        complete: -> {}
+      )
+
+      @subscriptions << @ws.subscribe(
+        <<~GQL, nil,
+          subscription PlaylistChanged {
+            playlistChanged {
+              amount index maxPlaylistSize firstIndex lastInsertPos seed lastShuffledStart
+              tracks { id title artist album path length albumArt }
+            }
+          }
+        GQL
+        next: ->(result) {
+          payload = result[:data]&.dig(:playlist_changed)
+          if payload
+            tracks = Array(payload[:tracks]).map { |t| Track.from_hash(t) }
+            playlist = Rockbox::Playlist.new(
+              amount:              payload[:amount],
+              index:               payload[:index],
+              max_playlist_size:   payload[:max_playlist_size],
+              first_index:         payload[:first_index],
+              last_insert_pos:     payload[:last_insert_pos],
+              seed:                payload[:seed],
+              last_shuffled_start: payload[:last_shuffled_start],
+              tracks:              tracks
+            )
+            @events.emit(:playlist_changed, playlist)
+          end
+        },
+        error: ->(err) { @events.emit(:ws_error, wrap_error(err)) },
+        complete: -> {}
+      )
+
+      @events.emit(:ws_open)
+      self
+    end
+
+    # Tear down subscriptions and close the WebSocket.
+    def disconnect
+      @subscriptions.each { |unsub| unsub.call rescue nil }
+      @subscriptions.clear
+      @ws.dispose
+      @events.emit(:ws_close)
+      self
+    end
+
+    # ---------------------------------------------------------------------------
+    # Plugin system
+    # ---------------------------------------------------------------------------
+
+    # @example
+    #   client.use(MyScrobbler.new(api_key: "..."))
+    def use(plugin)
+      ctx = PluginContext.new(
+        query: ->(gql, variables = nil) { @http.execute(gql, variables) },
+        events: @events
+      )
+      @plugins.register(plugin, ctx)
+      self
+    end
+
+    def unuse(name)
+      @plugins.unregister(name)
+      self
+    end
+
+    def installed_plugins
+      @plugins.list
+    end
+
+    # ---------------------------------------------------------------------------
+    # Raw escape hatch — for one-off GraphQL operations
+    # ---------------------------------------------------------------------------
+
+    # @param query     [String]
+    # @param variables [Hash, nil]
+    # @return [Hash] the snake-cased data object
+    def query(query, variables = nil)
+      @http.execute(query, variables)
+    end
+
+    private
+
+    def wrap_error(err)
+      err.is_a?(Exception) ? err : NetworkError.new(err.to_s)
+    end
+  end
+end

data/lib/rockbox/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Rockbox
+  # Mutable configuration holder used by the builder block API.
+  #
+  # @example
+  #   client = Rockbox::Client.build do |c|
+  #     c.host = "192.168.1.42"
+  #     c.port = 6062
+  #   end
+  class Configuration
+    DEFAULT_HOST = "localhost"
+    DEFAULT_PORT = 6062
+
+    attr_accessor :host, :port, :http_url, :ws_url, :open_timeout, :read_timeout
+
+    def initialize(host: nil, port: nil, http_url: nil, ws_url: nil,
+                   open_timeout: nil, read_timeout: nil)
+      @host         = host
+      @port         = port
+      @http_url     = http_url
+      @ws_url       = ws_url
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def resolved_host;  @host  || DEFAULT_HOST end
+    def resolved_port;  @port  || DEFAULT_PORT end
+
+    def resolved_http_url
+      @http_url || "http://#{resolved_host}:#{resolved_port}/graphql"
+    end
+
+    def resolved_ws_url
+      @ws_url || "ws://#{resolved_host}:#{resolved_port}/graphql"
+    end
+  end
+end

data/lib/rockbox/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rockbox
+  # Base class for every error raised by the SDK.
+  class Error < StandardError
+    attr_reader :cause
+
+    def initialize(message, cause: nil)
+      super(message)
+      @cause = cause
+    end
+  end
+
+  # Raised when the HTTP/WebSocket transport cannot reach rockboxd.
+  class NetworkError < Error; end
+
+  # Raised when rockboxd returns a GraphQL `errors` payload.
+  #
+  # @example
+  #   begin
+  #     client.playback.play
+  #   rescue Rockbox::GraphQLError => e
+  #     puts e.errors.first[:message]
+  #   end
+  class GraphQLError < Error
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = Array(errors)
+      super(@errors.map { |e| e[:message] || e["message"] }.compact.join("; "))
+    end
+  end
+end