mpv-ipc 5.0.0

data/lib/mpv_ipc/client.rb

@@ -0,0 +1,529 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "concurrent"
+
+require_relative "exceptions"
+require_relative "multi_queue"
+require_relative "../mpv_ass"
+
+module MPV
+  # Represents a connection to an `mpv` process over an IPC socket.
+  # @see https://mpv.io/manual/stable/#json-ipc
+  #  MPV's IPC docs
+  # @see https://mpv.io/manual/stable/#properties
+  #  MPV's property docs
+  class Client
+    # Alternative constructor for mpv embedded script mode.
+    # @return [MPV::Client] a new instance of this class
+    #  using a file descriptor from `--mpv-ipc-fd` argument
+    def self.script
+      require "optparse"
+      OptionParser.new do |opts|
+        opts.on("--mpv-ipc-fd=N", Integer){ |fd| return new(fd) }
+      end.parse!
+      raise ArgumentError, "--mpv-ipc-fd argument not provided"
+    end
+
+    # Creates a new MPV::Client instance.
+    # @param conn [Object] mpv connection descriptor
+    #  It can be a Unix socket path as a [String], an already connected [Socket]
+    #  or its raw file descriptor as an [Integer], or a custom IO-like object
+    #  with standard gets() and puts() methods.
+    def initialize(conn)
+      @socket = case conn
+        when String then UNIXSocket.new(@path = conn)
+        when Integer then Socket.for_fd(conn)
+        else conn
+      end
+      @request_id = Concurrent::AtomicFixnum.new(MIN_REQ_ID - 1)
+      @reply_queue = MultiQueue.new(RESPONSE_TIMEOUT)
+      @event_listeners = Concurrent::Hash.new
+      @property_observers = Concurrent::Hash.new
+      @message_handlers = Concurrent::Hash.new
+      @keybinding_handlers = Concurrent::Hash.new
+      @osd_messages = Concurrent::Hash.new
+      @event_queue = Queue.new
+      @cmd_mutex = Mutex.new
+      @keybinding_mutex = Mutex.new
+      @osd_mutex = Mutex.new
+      @shutdown_callback = nil
+      @link_thread = Thread.new(&method(:link_loop))
+      @link_thread.name = "mpv link"
+      @event_thread = Thread.new(&method(:event_loop))
+      @event_thread.name = "mpv event"
+    end
+
+    # Checks whether the mpv connection is still alive.
+    # @return [Boolean] true if the connection is alive
+    def alive?
+      @link_thread.alive?
+    end
+
+    # Waits for the mpv connection to terminate.
+    # @param timeout [Numeric] optional timeout in seconds
+    # @return [Boolean] whether the connection was terminated
+    def wait(timeout=nil)
+      !!@link_thread.join(timeout)
+    end
+
+    # Terminates the mpv communication.
+    # @return [void]
+    def release!
+      @link_thread.exit
+      @link_thread.join
+    end
+
+    # Sends a `quit` command to shut down the `mpv` process and
+    # releases the communication with it.
+    # @return [Boolean] true if the `quit` command was sent successfully
+    def quit!
+      command!("quit")
+      @link_thread.join
+      true
+    rescue
+      @link_thread.exit
+      @link_thread.join
+      false
+    end
+
+    # Sends a command to the `mpv` process.
+    # @param args [Array] the individual command arguments to send
+    # @raise [MPV::TimeoutError] if the request has timed out
+    # @raise [MPV::ConnectionError] in case of any socket error
+    # @raise [MPV::ReleasedConnectionError] if there is no connection anymore
+    # @return [Reply] mpv's response struct
+    # @example
+    #  client.command("loadfile", "mymovie.mp4", "append-play").success? # => true
+    #  client.command("asdfgh", "myparam").success? # => false
+    #  client.command("asdfgh", "myparam").error # => "invalid parameter"
+    def command(*args)
+      raise ReleasedConnectionError unless alive?
+      @reply_queue.open(next_id) do |queue|
+        payload = { command: args, request_id: queue.id, async: true }
+        @cmd_mutex.synchronize{ @socket.puts(JSON.fast_generate(payload)) }
+        queue.pop
+      end
+    rescue IOError, SystemCallError => exc
+      raise ConnectionError, exc
+    end
+
+    # Sends a command to the `mpv` process and then checks if it was successful.
+    # @param args [Array] the individual command arguments to send
+    # @raise [MPV::TimeoutError] if the request has timed out
+    # @raise [MPV::ConnectionError] in case of any socket error
+    # @raise [MPV::ReleasedConnectionError] if there is no connection anymore
+    # @raise [MPV::ReplyError] if the response is unsuccessful
+    # @return [Object] mpv's response data value
+    # @example
+    #  client.command!("loadfile", "mymovie.mp4", "append-play") # => nil
+    #  client.command!("asdfgh", "myparam") # => raises MPV::ReplyError
+    def command!(*args)
+      command(*args).data!
+    end
+
+    # Retrieves a property from the `mpv` process.
+    # @param name [String] the property name (e.g.: volume)
+    # @return [Reply] mpv's response struct
+    # @example
+    #  client.get_property("pause").data # => true
+    #  client.get_property("volume").data # => 100.0
+    #  client.get_property("asdfgh").data # => nil
+    #  client.get_property("asdfgh").error # => "property not found"
+    def get_property(name)
+      command("get_property", name)
+    end
+
+    # Retrieves a property from the `mpv` process and then confirms success.
+    # @param name [String] the property name (e.g.: volume)
+    # @raise [MPV::ReplyError] if the response is unsuccessful
+    # @return [Object] mpv's response data value
+    # @example
+    #  client.get_property!("pause") # => true
+    #  client.get_property!("volume") # => 100.0
+    #  client.get_property!("asdfgh") # => raises MPV::ReplyError
+    def get_property!(name)
+      get_property(name).data!
+    end
+
+    # Sends a property change to the `mpv` process.
+    # @param name [String] the property name (e.g.: volume)
+    # @param value [Object] property value
+    # @return [Reply] mpv's response struct
+    # @example
+    #  client.set_property("pause", true).success? # => true
+    #  client.set_property("volume", 100.0).success? # => true
+    #  client.set_property("asdfgh", 42).success? # => false
+    #  client.set_property("asdfgh", 42).error # => "property not found"
+    def set_property(name, value)
+      command("set_property", name, value)
+    end
+
+    # Sends a property change to the `mpv` process and then confirms success.
+    # @param name [String] the property name (e.g.: volume)
+    # @param value [Object] property value
+    # @raise [MPV::ReplyError] if the response is unsuccessful
+    # @return [Object] mpv's response data value
+    # @example
+    #  client.set_property!("pause", true) # => nil
+    #  client.set_property!("volume", 100.0) # => nil
+    #  client.set_property!("asdfgh", 42) # => raises MPV::ReplyError
+    def set_property!(name, value)
+      set_property(name, value).data!
+    end
+
+    # Observes property changes.
+    # @param name [String] name of the property to observe
+    # @yield [ObserverEvent] event triggered by a property change
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @return [Integer] the observer id to use with unobserve_property
+    # @example
+    #  client.observe_property("volume") do |event|
+    #   puts "the new volume is #{event.data}"
+    #  end
+    def observe_property(name, &block)
+      id = next_id
+      @property_observers[id] = block
+      command!("observe_property", id, name)
+      id
+    rescue
+      @property_observers.delete(id)
+      raise
+    end
+
+    # Unobserves property changes.
+    # @param id [Integer] the return value of #observe_property
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @return [void]
+    def unobserve_property(id)
+      command!("unobserve_property", id)
+      @property_observers.delete(id)
+    end
+
+    # Registers an event listener.
+    # @param name [String] event name to listen for (defaults to all)
+    # @yield [Event] called with the event descriptor object
+    # @return [void]
+    def register_event_listener(name="", &block)
+      @event_listeners[name] = block
+    end
+
+    # Unregisters an event listener.
+    # @param name [String] name of the listened event (defaults to all)
+    # @return [void]
+    def unregister_event_listener(name="")
+      @event_listeners.delete(name)
+    end
+
+    # Registers a client-message handler.
+    # @param message [String] the script-message identifier
+    # @yield [Array] called with the arguments passed to client-message
+    # @return [void]
+    # @example
+    #  client.register_message_handler("cool-message") do |a, b|
+    #    puts "hello #{a}-#{b}" # => hello, mikuru-chan
+    #  end
+    #
+    #  client.command("script-message", "cool-message", "mikuru", "chan")
+    def register_message_handler(message, &block)
+      @message_handlers[message] = block
+    end
+
+    # Unregisters a client-message handler.
+    # @param message [String] the client-message identifier
+    # @return [void]
+    def unregister_message_handler(message)
+      @message_handlers.delete(message)
+    end
+
+    # Registers a keybinding section.
+    # @param keys [Array<String>] key names to bind (in input.conf format)
+    # @param section [String] optional custom section name
+    # @param flags [Symbol] optional key binding priority (default: :default)
+    #   :default lets user bindings win, while :force overrides them
+    # @yield [KeyEvent] the keybinding event
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @return [String] section name (for unregister_keybindings)
+    # @example
+    #  client.register_keybindings("a", "b") do |key_event|
+    #    key_event.hold? # => true
+    #    key_event.key # => "b"
+    #  end
+    #
+    #  client.command("keypress", "b")
+    def register_keybindings(*keys, section: nil, flags: :default, &block)
+      section ||= "sect_#{next_id}"
+      contents = keys.flatten.map{ |key| "#{key} script-binding #{client_name}/#{section}" }
+      @keybinding_mutex.synchronize do
+        @keybinding_handlers[section] = block
+        command!("define-section", section, contents.join("\n"), flags)
+        command!("enable-section", section)
+      rescue
+        @keybinding_handlers.delete(section)
+        raise
+      end
+      section
+    end
+
+    # Unregisters a keybinding section.
+    # @param section [String] section name
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @return [void]
+    def unregister_keybindings(section)
+      @keybinding_mutex.synchronize do
+        command!("disable-section", section)
+        command!("define-section", section, "")
+        @keybinding_handlers.delete(section)
+      end
+    end
+
+    # Creates a new message and adds it to the OSD.
+    # @param text [String, Ass::Text] message
+    # @param timeout [Numeric] optional timeout in seconds to autoremove the message
+    #   If omitted or non-positive, the message is not scheduled for automatic removal.
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @return [Integer] message id
+    def create_osd_message(text, timeout: nil)
+      id = next_id
+      @osd_messages[id] = nil, nil
+      edit_osd_message(id, text, timeout: timeout)
+      id
+    rescue
+      @osd_messages.delete(id)
+      raise
+    end
+
+    # Edits one of the messages on the OSD.
+    # @param id [Integer] message id
+    # @param text [String, Ass::Text] message
+    # @param timeout [Numeric] optional timeout in seconds to autoremove the message
+    #   If omitted, the timeout remains unchanged. If non-positive, autoremove is disabled.
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @return [Boolean] true if the message with the given id still existed
+    def edit_osd_message(id, text, timeout: nil)
+      text = Ass::Text.new(text) unless text.is_a?(Ass::Text)
+      @osd_mutex.synchronize do
+        if record = @osd_messages[id]
+          record[0] = text.to_script
+          render_osd_messages
+          if timeout
+            if timeout.positive?
+              unless record[1]&.reschedule(timeout)
+                record[1] = task = Concurrent::ScheduledTask.execute(timeout) do
+                  @osd_mutex.synchronize do
+                    if @osd_messages.dig(id, 1) == task
+                      @osd_messages.delete(id)
+                      render_osd_messages
+                    end
+                  end
+                end
+              end
+            elsif record[1]
+              record[1].cancel
+              record[1] = nil
+            end
+          end
+        end
+        !!record
+      end
+    end
+
+    # Deletes one of the messages on the OSD.
+    # @param id [Integer] message id
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @return [void]
+    def delete_osd_message(id)
+      @osd_mutex.synchronize do
+        if record = @osd_messages.delete(id)
+          record[1]&.cancel
+          render_osd_messages
+        end
+      end
+      nil
+    end
+
+    # Deletes all messages on the OSD.
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @return [void]
+    def clear_osd_messages
+      @osd_mutex.synchronize do
+        unless @osd_messages.empty?
+          @osd_messages.each_value{ |(_, scheduler)| scheduler&.cancel }
+          @osd_messages.clear
+          render_osd_messages
+        end
+      end
+      nil
+    end
+
+    # Enters a modal mode, similar to Vim's modes, but exits after a
+    # single keypress or when the exit key is pressed.
+    # @param message [String] message to show while the modal mode is active
+    # @param keys [Array<String>] the keys to bind (in input.conf format)
+    # @param exit_key [String] the key to exit modal mode (in input.conf format)
+    # @raise [MPV::ReplyError] if mpv rejects an underlying command
+    # @yield [KeyEvent] the keybinding event
+    # @return [String] section name (for unregister_keybindings)
+    # @example
+    #  client.register_keybindings(%w[d]) do
+    #    client.enter_modal_mode("really delete?", %w[y n]) do |key_event|
+    #      key_event.press? # => true
+    #      key_event.key # => "y"
+    #    end
+    #  end
+    def enter_modal_mode(message, keys, exit_key: "ESC", &block)
+      osd_id = create_osd_message(message)
+      register_keybindings(*keys, exit_key, flags: :force) do |event|
+        delete_osd_message(osd_id) rescue nil
+        unregister_keybindings(event.section) rescue nil
+        block.call(event) if block_given? && event.key != exit_key
+      end
+    rescue
+      delete_osd_message(osd_id) rescue nil
+      raise
+    end
+
+    # Registers a shutdown callback for notification or cleanup.
+    # @yield [Boolean] called after the mpv connection is closed
+    #   with true if the server initiated the socket closure
+    # @return [void]
+    def register_shutdown_callback(&block)
+      @shutdown_callback = block
+    end
+
+    # Unregisters the current shutdown callback.
+    # @return [void]
+    def unregister_shutdown_callback
+      @shutdown_callback = nil
+    end
+
+  private
+    Reply = Struct.new(:data, :error, keyword_init: true) do
+      def success?
+        error == "success"
+      end
+      def error?
+        !success?
+      end
+      def data!
+        raise ReplyError, error if error?
+        data
+      end
+    end
+
+    Event = Struct.new(:name, :raw, keyword_init: true)
+
+    ObserverEvent = Struct.new(:name, :data, :raw, keyword_init: true)
+
+    KeyEvent = Struct.new(:section, :state, :key, :key2, :raw) do
+      def up?
+        state == "u-"
+      end
+      def down?
+        state == "d-"
+      end
+      def hit?
+        state == "p-"
+      end
+      def repeat?
+        state == "r-"
+      end
+      def press?
+        hit? or down?
+      end
+      def hold?
+        press? or repeat?
+      end
+    end
+
+    RESPONSE_TIMEOUT = 6 # sec
+
+    # Don't use 0, mpv observers don't work otherwise, it's treated as nil.
+    MIN_REQ_ID = 1
+
+    # The virtual machine's maximum Fixnum. Equals 2^62 on CRuby compiled
+    # on a 64-bit machine, and up to 2^64 on VMs like JRuby. mpv goes up
+    # to 2^64, so this is a safe value to make the atomic counter roll over.
+    MAX_REQ_ID = (2**(0.size * 8 - 2) - 1)
+
+    def next_id
+      @request_id.update{ |current| current < MAX_REQ_ID ? current + 1 : MIN_REQ_ID }
+    end
+
+    def client_name
+      @client_name ||= command!("client_name")
+    end
+
+    def render_osd_messages
+      if @osd_messages.empty?
+        command!("osd-overlay", 0, "none", "")
+      else
+        scripts = @osd_messages.values.map(&:first)
+        command!("osd-overlay", 0, "ass-events", scripts.join("\n"))
+      end
+    end
+
+    def dispatch_property_observer(event)
+      if observer = @property_observers[event.raw["id"]]
+        property = event.raw.slice("name", "data")
+        @event_queue.push([observer, ObserverEvent.new(**property, raw: event.raw)])
+      end
+    end
+
+    def dispatch_message_handler(event)
+      message, *args = event.raw["args"]
+
+      if message == "key-binding" and handler = @keybinding_handlers[args.first]
+        @event_queue.push([handler, KeyEvent.new(*args.values_at(0..3), event.raw)])
+      end
+
+      handler = @message_handlers[message]
+      @event_queue.push([handler, *args]) if handler
+    end
+
+    def dispatch_event_listener(event)
+      listener = @event_listeners[event.name]
+      @event_queue.push([listener, event]) if listener
+
+      listener = @event_listeners[""]
+      @event_queue.push([listener, event]) if listener
+    end
+
+    def dispatch_event_handlers(event)
+      case event.name
+        when "property-change" then dispatch_property_observer(event)
+        when "client-message" then dispatch_message_handler(event)
+      end
+      dispatch_event_listener(event)
+    end
+
+    def link_loop
+      while line = @socket.gets and line.chomp!
+        response = JSON.parse(line) rescue {}
+        if response.key?("event")
+          event = Event.new(name: response["event"], raw: response)
+          dispatch_event_handlers(event)
+        elsif response.key?("request_id")
+          reply = Reply.new(response.slice("data", "error"))
+          @reply_queue.push(response["request_id"], reply)
+        end
+      end
+      eof = !line
+    rescue
+    ensure
+      @socket.close if @path
+      if @shutdown_callback
+        @event_queue.push([@link_thread.method(:join)])
+        @event_queue.push([@shutdown_callback, !!eof])
+      end
+      @event_queue.close
+    end
+
+    def event_loop
+      while event = @event_queue.pop
+        event.shift.call(*event) rescue nil
+      end
+    end
+  end
+end

data/lib/mpv_ipc/exceptions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module MPV
+  # Generic error class, all exceptions inherit from this.
+  class Error < RuntimeError
+  end
+
+  # Raised when an mpv reply is unsuccessful.
+  class ReplyError < Error
+  end
+
+  # Raised when a request has timed out.
+  class TimeoutError < Error
+    def initialize
+      super "Request timed out"
+    end
+  end
+
+  # Raised when some socket communication error occurs.
+  # The connection will be released.
+  class ConnectionError < Error
+    def initialize(msg=nil)
+      super(msg.is_a?(String) ? msg :
+        "Socket communication error occurred with the mpv#{": #{msg}" if msg}")
+    end
+  end
+
+  # Raised when the connection to mpv has already been released.
+  class ReleasedConnectionError < ConnectionError
+    def initialize
+      super "Connection released, further communication with mpv is not possible"
+    end
+  end
+
+  # Raised when the mpv startup has failed.
+  class StartupError < Error
+    def initialize(msg=nil)
+      super("Failed to start mpv#{": #{msg}" if msg}")
+    end
+  end
+
+  # Raised when no usable `mpv` executable is available.
+  class NotAvailableError < Error
+    def initialize
+      super "No usable mpv executable available"
+    end
+  end
+
+  # Raised when `mpv` doesn't support a requested option.
+  class UnsupportedOptionError < Error
+    def initialize(option)
+      super "The installed mpv does not support the #{option} option"
+    end
+  end
+end

data/lib/mpv_ipc/multi_queue.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "exceptions"
+
+module MPV
+  # Holds state to handle request/response lifecycle for mpv's ipc protocol.
+  class MultiQueue
+    class Reader
+      attr_reader :id
+
+      def initialize(table, id)
+        table.instance_variables.each do |var|
+          instance_variable_set(var, table.instance_variable_get(var))
+        end
+        @mutex.synchronize{ @table[@id = id] ||= [] }
+      end
+
+      # Closes this queue.
+      def close
+        @mutex.synchronize{ @resource.broadcast if @table.delete(@id) }
+      end
+
+      # Pops a value from this queue.
+      # @param timeout [Numeric] optional (non-default) timeout in seconds
+      # @raise [MPV::TimeoutError] if timed out
+      # @raise [KeyError] if already closed 
+      # @return [Object] the value
+      def pop(timeout=@timeout)
+        @mutex.synchronize do
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout if timeout
+          while (queue = @table.fetch(@id)).empty?
+            raise TimeoutError if timeout&.negative?
+            @resource.wait(@mutex, timeout)
+            timeout &&= deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+          queue.pop
+        end
+      end
+    end
+
+    # Creates a new MPV::MultiQueue instance.
+    # @param timeout [Numeric] default timeout for pops in seconds
+    def initialize(timeout=nil)
+      @timeout = timeout
+      @table = Hash.new
+      @mutex = Mutex.new
+      @resource = ConditionVariable.new
+    end
+
+    # Opens a new queue for a certain unique id.
+    # @param id [Integer] the unique queue id
+    # @yield [Reader] if given, yields the queue reader
+    #  then closes it and returns the block’s result.
+    # @return [Object] new queue reader, or the block's result if given
+    def open(id, &block)
+      reader = Reader.new(self, id)
+      block ? block.call(reader) : reader
+    ensure
+      reader.close if block and reader
+    end
+
+    # Pushes a value to a certain queue.
+    # @param id [Integer] the unique queue id
+    # @param value [Object] the value
+    # @return [Boolean] whether the push was successful
+    def push(id, value)
+      @mutex.synchronize do
+        if queue = @table[id]
+          queue.push(value)
+          @resource.broadcast
+        end
+        !!queue
+      end
+    end
+  end
+end