mpv-ipc 5.0.0

data/lib/mpv_ipc/server.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "open3"
+require "concurrent"
+
+require_relative "utils"
+require_relative "exceptions"
+
+module MPV
+  # Represents an active `mpv` process started with an IPC socket.
+  # @note Resources are released by calling `#wait` after termination.
+  #  At exit, all running `mpv` processes are automatically stopped.
+  class Server
+    # @return [Array<String>] command-line options used when spawning `mpv`
+    attr_reader :options
+
+    # @return [String] the path to the currently used `mpv`
+    attr_reader :mpv_path
+
+    # @return [String] the path to the IPC socket used by this `mpv` process
+    attr_reader :ipc_path
+
+    @@existing_servers = Concurrent::Array.new
+    at_exit do
+      existing_servers = @@existing_servers.to_a
+      existing_servers.each{ |server| server.kill! }
+      existing_servers.each{ |server| server.wait }
+    end
+
+    # Creates a new MPV::Server instance and starts the `mpv` process.
+    # @param bind [String] the path of the IPC socket to be used
+    #  for the communication (defaults to a temporary path in `/tmp`)
+    # @param mpv [String] the path of the `mpv` executable
+    #  (defaults to searching in system `$PATH`)
+    # @param options [Array<String>] additional initial options to pass
+    #  to the `mpv` process
+    # @param chdir [String] custom working directory for `mpv`
+    # @raise [MPV::StartupError] if the `mpv` process fails to start
+    # @raise [MPV::NotAvailableError] if no `mpv` executable is available
+    # @raise [MPV::UnsupportedOptionError] if a given `mpv` option is not supported
+    def initialize(bind: nil, mpv: nil, options: [], chdir: nil)
+      @mpv_path = mpv || Utils.which("mpv")
+      raise NotAvailableError unless @mpv_path
+
+      @ipc_path = bind || File.join("/tmp", Utils.tmpsock)
+      File.delete(@ipc_path) if File.exist?(@ipc_path)
+
+      @options = options.map{ |option| option.sub(/\A-{1,2}/, "") }
+      @options << "terminal=no" << "input-ipc-server=#{@ipc_path}" << "idle=yes"
+
+      stdout, status = Open3.capture2(@mpv_path, "--list-options") rescue nil
+      raise NotAvailableError unless status&.success?
+      available_options = stdout.scan(/^\s*--(\S+)/).map(&:first)
+      @options.each{ |option| ensure_option!(option, available_options) }
+
+      args = @options.map{ |option| "--#{option}" }
+      params = {pgroup: true}.merge(({chdir: chdir} if chdir).to_h)
+      @pid = Process.spawn(@mpv_path, *args, **params)
+
+      timeout = Process.clock_gettime(Process::CLOCK_MONOTONIC) + STARTUP_TIMEOUT
+      until File.exist?(@ipc_path)
+        if status = Process.wait2(@pid, Process::WNOHANG)&.last
+          raise StartupError, "unexpected termination with " \
+            "#{status.to_s.delete_prefix("pid #{status.pid} ")}"
+        end
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > timeout
+          Process.kill(:KILL, -@pid)
+          Process.wait(@pid)
+          raise StartupError, "timed out"
+        end
+        sleep 0.02
+      end
+
+      @@existing_servers << self
+    end
+
+    # Checks whether the `mpv` process is still alive.
+    # @return [Boolean] true if the `mpv` process is alive
+    def alive?
+      @pid = nil if wait_pid(@pid, false)
+      !!@pid
+    end
+
+    # Blocks until the `mpv` process is terminated, then releases all resources.
+    # @return [void]
+    def wait
+      wait_pid(@pid, true)
+      File.delete(@ipc_path) rescue nil if @ipc_path
+      @pid = @ipc_path = nil
+      @@existing_servers.delete(self)
+    end
+
+    # Sends a signal to the `mpv` process.
+    # @param signal [Object] the name (String/Symbol) or code (Integer)
+    #  of the signal to send
+    # @return [Boolean] true if the signal was sent successfully
+    def kill!(signal=:TERM)
+      pid = @pid
+      Process.kill(signal, -pid) if pid
+      !!pid
+    rescue Errno::ESRCH
+      false
+    end
+
+  private
+    STARTUP_TIMEOUT = 6 # sec
+
+    def ensure_option!(option, available_options)
+      # Options can be prefixed with `no-` (equivalent to a `=no` suffix),
+      # but these variations aren’t included in the list of supported options,
+      # so these need to be removed before checking.
+      opt = option.sub(/\A(?:no-)?(.*?)(?:=.*)?\z/, "\\1")
+      raise UnsupportedOptionError, opt unless available_options.include?(opt)
+    end
+
+    def wait_pid(pid, blocking)
+      !pid || !!Process.wait(pid, blocking ? 0 : Process::WNOHANG)
+    rescue Errno::ECHILD
+      true
+    end
+  end
+end

data/lib/mpv_ipc/session.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+require_relative "client"
+require_relative "server"
+
+module MPV
+  # Combines an MPV::Server and MPV::Client, connecting them to each other.
+  # @note Automatically releases resources after termination.
+  class Session
+    extend Forwardable
+
+    # @return [MPV::Server] the server object responsible for the mpv process
+    attr_reader :server
+
+    # @return [MPV::Client] the client communicating with mpv
+    attr_reader :client
+
+    # Creates a new MPV::Session instance containing an MPV::Server and an
+    # MPV::Client that are connected to each other.
+    # All parameters are passed to MPV::Server.
+    # @see MPV::Server::new
+    def initialize(**params)
+      @server = Server.new(**params)
+      @client = Client.new(@server.ipc_path)
+
+      @shutdown_callback = nil
+      @client.register_shutdown_callback do |eof|
+        @shutdown_callback.call(eof) if @shutdown_callback
+      ensure
+        @server.wait if Thread.main.alive?
+      end
+    rescue
+      if @server
+        @server.kill!
+        @server.wait
+      end
+      raise
+    end
+
+    # Registers a shutdown callback for notification or cleanup.
+    # @yield [Boolean] called with a boolean indicating whether
+    #  the server closed the connection properly
+    # @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
+
+    # Terminates the mpv process and waits for it.
+    # It releases all the resources.
+    # @return [Boolean] false if it was already terminated
+    def quit!
+      result = @client.quit! || @server.kill!
+      @server.wait
+      result
+    end
+
+    # @!method alive?
+    # @return (see MPV::Client#alive?)
+    # @see MPV::Client#alive?
+    def_delegators :@client, :alive?
+
+    # @!method wait
+    # @return (see MPV::Client#wait)
+    # @see MPV::Client#wait
+    def_delegators :@client, :wait
+
+    # @!method command
+    # @return (see MPV::Client#command)
+    # @see MPV::Client#command
+    def_delegators :@client, :command
+
+    # @!method command!
+    # @return (see MPV::Client#command!)
+    # @see MPV::Client#command!
+    def_delegators :@client, :command!
+
+    # @!method get_property
+    # @return (see MPV::Client#get_property)
+    # @see MPV::Client#get_property
+    def_delegators :@client, :get_property
+
+    # @!method get_property!
+    # @return (see MPV::Client#get_property!)
+    # @see MPV::Client#get_property!
+    def_delegators :@client, :get_property!
+
+    # @!method set_property
+    # @return (see MPV::Client#set_property)
+    # @see MPV::Client#set_property
+    def_delegators :@client, :set_property
+
+    # @!method set_property!
+    # @return (see MPV::Client#set_property!)
+    # @see MPV::Client#set_property!
+    def_delegators :@client, :set_property!
+
+    # @!method observe_property
+    # @return (see MPV::Client#observe_property)
+    # @see MPV::Client#observe_property
+    def_delegators :@client, :observe_property
+
+    # @!method unobserve_property
+    # @return (see MPV::Client#unobserve_property)
+    # @see MPV::Client#unobserve_property
+    def_delegators :@client, :unobserve_property
+
+    # @!method register_event_listener
+    # @return (see MPV::Client#register_event_listener)
+    # @see MPV::Client#register_event_listener
+    def_delegators :@client, :register_event_listener
+
+    # @!method unregister_event_listener
+    # @return (see MPV::Client#unregister_event_listener)
+    # @see MPV::Client#unregister_event_listener
+    def_delegators :@client, :unregister_event_listener
+
+    # @!method register_message_handler
+    # @return (see MPV::Client#register_message_handler)
+    # @see MPV::Client#register_message_handler
+    def_delegators :@client, :register_message_handler
+
+    # @!method unregister_message_handler
+    # @return (see MPV::Client#unregister_message_handler)
+    # @see MPV::Client#unregister_message_handler
+    def_delegators :@client, :unregister_message_handler
+
+    # @!method register_keybindings
+    # @return (see MPV::Client#register_keybindings)
+    # @see MPV::Client#register_keybindings
+    def_delegators :@client, :register_keybindings
+
+    # @!method unregister_keybindings
+    # @return (see MPV::Client#unregister_keybindings)
+    # @see MPV::Client#unregister_keybindings
+    def_delegators :@client, :unregister_keybindings
+
+    # @!method create_osd_message
+    # @return (see MPV::Client#create_osd_message)
+    # @see MPV::Client#create_osd_message
+    def_delegators :@client, :create_osd_message
+
+    # @!method edit_osd_message
+    # @return (see MPV::Client#edit_osd_message)
+    # @see MPV::Client#edit_osd_message
+    def_delegators :@client, :edit_osd_message
+
+    # @!method delete_osd_message
+    # @return (see MPV::Client#delete_osd_message)
+    # @see MPV::Client#delete_osd_message
+    def_delegators :@client, :delete_osd_message
+
+    # @!method clear_osd_messages
+    # @return (see MPV::Client#clear_osd_messages)
+    # @see MPV::Client#clear_osd_messages
+    def_delegators :@client, :clear_osd_messages
+
+    # @!method enter_modal_mode
+    # @return (see MPV::Client#enter_modal_mode)
+    # @see MPV::Client#enter_modal_mode
+    def_delegators :@client, :enter_modal_mode
+  end
+end

data/lib/mpv_ipc/utils.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module MPV
+  # Various utility methods for mpv-ipc.
+  module Utils
+    # Finds where the given utility is located in the system paths.
+    # @param name [String] name of the utility to find
+    # @return [String] full path of the utility
+    # @api private
+    def self.which(name)
+      paths = ENV["PATH"].split(File::PATH_SEPARATOR).map{ |dir| File.join(dir, name) }
+      paths.find{ |path| File.file?(path) && File.executable?(path) }
+    end
+
+    def self.tmpsock
+      "mpv-ipc-#{$$}-#{Time.now.strftime("%Y%m%d%N")}-#{rand(36**8).to_s(36)}.sock"
+    end
+  end
+end

data/lib/mpv_ipc/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module MPV
+  # The current version of mpv-ipc.
+  VERSION = "5.0.0"
+end

data/lib/mpv_ipc.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "mpv_ipc/version"
+require_relative "mpv_ipc/session"

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: mpv-ipc
+version: !ruby/object:Gem::Version
+  version: 5.0.0
+platform: ruby
+authors:
+- Péter Bakonyi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.6
+description: |-
+  A Ruby interface to the mpv media player via its JSON IPC protocol.
+  It can start and manage mpv instances, connect to and control existing players, or be used to write Ruby scripts that run embedded within mpv.
+email: bakonyi.peter@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mpv_ass.rb
+- lib/mpv_ass/color.rb
+- lib/mpv_ass/span.rb
+- lib/mpv_ass/text.rb
+- lib/mpv_ipc.rb
+- lib/mpv_ipc/client.rb
+- lib/mpv_ipc/exceptions.rb
+- lib/mpv_ipc/multi_queue.rb
+- lib/mpv_ipc/server.rb
+- lib/mpv_ipc/session.rb
+- lib/mpv_ipc/utils.rb
+- lib/mpv_ipc/version.rb
+homepage: https://github.com/BPeti/mpv-ipc
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/BPeti/mpv-ipc
+  documentation_uri: https://www.rubydoc.info/gems/mpv-ipc
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: A simple interface to mpv via JSON IPC.
+test_files: []