alsactl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 867a15dbe3727200b48ae90e35ad96c010bb19395b94f70629e2564979b2c76a
+  data.tar.gz: b19233f1ee8a13d44fef4daaf58eab05077c50418299ff590966b8b35ae0aa18
+SHA512:
+  metadata.gz: 6a5945c2b798ddee40b49fcff6fd35de7cc00063210464743eee7195022c4ac7c56c250df6fe3bc921f8cac9e381f005d856d956f53345cf44f379ab89d964fd
+  data.tar.gz: b5832781e76557308f42a34253ad9978f5c90812cce6e96cb286793592c99d392f44ef407a43a780d93cbb308fc2fab776718529301ef78a2fad7d3b69264e53

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+### CHANGELOG -- (Ruby AlsaCtl) ###
+1) 0.1.0, unreleased: 2021-May-04 -- Changed the API to use Ruby as the complex implementation interface, because faster to get it done, less code, and way simpler than doing all the higher-order calculations (as well as string and symbol comparisons) in the C wrapper. [t. Edelweiss]
+1) 0.1.0, unreleased: 2021-May-04 -- In so doing above, turned entire C wrapper into an abstract class and module, so it can only be implemented by inheritance. Added such an implementation class, ``Mixers::DefMixer``. [t. Edelweiss]
+1) 0.1.0, immediate pre-release: 2021-May-09 -- Realized that this gem was named too generic and changed the name to AlsaCtl, as there is a reasonable chance I might need to also handle PulseAudio or other APIs, at some point. Please also note the difference in the GitHub repo URL.

data/LICENSE.txt

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -0,0 +1,43 @@
+### OVERVIEW ###
+AlsaCtl is a C-Ruby API wrapper with a pure Ruby middleware, for the ALSA library on Linux. By default, it handles the ``default/Master`` mixer object (current default volume controller). The base class, ``AlsaCore::BaseMixer`` cannot be instantiated, and all methods outside of allocation are protected, so it acts as an abstract-only class. However, you may derive from it, such as the ``AlsaCtl::DefMixer`` object ``(class DefMixer < AlsaCore::BaseMixer)``.
+
+### USAGE ###
+```ruby
+m = AlsaCtl::DefMixer.new # Creates a new default mixer object
+m.connect # By default, calls BaseMixer.connect("default", "Master")
+m.disconnect # Disconnects from the ALSA server -- do NOT use after, will cause crash (until I update)
+m.close # Same as above
+
+m.enum # List off all the valid channels for the device
+
+m.volume # Returns the volumes by channel
+m.vget # Same as above
+m.c_vget :channel_id # Get the volume of a specific channel
+# ex 1: m.c_vget 3 <- gets the volume of the 4th channel (indices start at 0)
+# ex 2: m.c_vget 300000 <- will return FALSE, b/c this channel isn't valid
+# ex 3: m.c_vget "pizza" <- will return NIL, b/c this TYPE isn't valid
+
+m.set_volume :percent, :change_type # Sets the volume of all channels
+m.vset :percent, :change_type # Same as above
+# ex 1: m.set_volume 15, -1 <- Turns the volume down by 15%
+# ex 2: m.set_volume 15, 1 <- Turns the volume up by 15%
+# ex 3: m.set_volume 15, 0 <- Turns the volume to 15%
+m.c_vset :channel, :percent, :change_type # Set single channel's volume
+# ex 1: m.c_vset 1, 15, :lower (or :down, :decrease) <- Turns the volume down by 15%
+# ex 2: m.c_vset 1, 15, :up (or :raise, :increase) <- Turns the volume up by 15%
+# ex 3: m.c_vset 1, 15, nil (or anything else) <- Turns the volume to 15%
+
+m.mute # Mutes the volume, storing the current volume or else a 50% default
+m.unmute # Unmutes the volume
+```
+
+### TO-DO ###
+1) Start the next version, 0.2.0 _WITH_ 
+1) Create derived class from ``DefMixer`` with non-flat volume modulation (such as for use in spatially-oriented physical speaker configurations)
+1) Derive other desirable classes for other common controllers
+1) EVENTUALLY, add PCM and capture classes
+
+### INSTALLATION ###
+```
+gem install alsactl
+```

data/ext/alsacore/extconf.rb

@@ -0,0 +1,10 @@
+# ext/alsacore/extconf.rb
+require 'mkmf'
+
+# Build MixCore
+$LFLAGS = '-lasound'
+have_library("asound")
+have_header("alsa/asoundlib.h")
+have_func("snd_mixer_open")
+have_func("snd_mixer_close")
+create_makefile("alsacore/alsacore")

data/lib/alsactl.rb

@@ -0,0 +1,7 @@
+# lib/alsactl.rb
+
+# This module include a C wrapper for
+# controlling basic Linux ALSA volume
+# settings on the system
+require_relative("./alsactl/mixers")
+require_relative("./alsactl/version")

data/lib/alsactl/mixers.rb

@@ -0,0 +1,259 @@
+# lib/alsactl/mixer.rb
+
+require_relative "../alsacore/alsacore"
+
+##
+# This extends the regular AlsaCore module and
+# includes classes abstracted from the C code
+# in the extension.
+# 
+# I realized that the vast majority of the actual
+# operations should be performed in an abstracted
+# class; and only core, concrete operations needed
+# to be included in the C code portion.
+module AlsaCtl
+  ##
+  # Finalized computation for a volume setting.
+  # 
+  # This is not intended to be used directly, but
+  # it helps separate functionality.
+  # 
+  # Returns the volume limit as a +FixedNum+, used
+  # as a +long+ in the C code portion of the extension.
+  def self.compute_final(min, max, adjustment)
+    case
+    when adjustment > max
+      max
+    when adjustment < min
+      min
+    else
+      adjustment
+    end
+  end # End finalized computation
+  
+  ##
+  # Compute the volume to set a channel.
+  # 
+  # Makes use of +compute_final+, as well as a type for
+  # the change. The type will be a symbol of any of the
+  # following values:
+  # 
+  # 1. +:raise+, +:up+, or +:increase+ to raise the volume.
+  # 2. +:lower+, +:down+, or +:decrease+ to lower the volume.
+  # 3. Any other value (use +nil+) to set the volume to a number.
+  def self.compute(min, max, current, perc_change, type_change)
+    change = ((max * perc_change) / 100).round
+    case type_change
+    when :raise, :up, :increase
+      self.compute_final(min, max, (current + change))
+    when :lower, :down, :decrease
+      self.compute_final(min, max, (current - change))
+    else
+      self.compute_final(min, max, change)
+    end
+  end # End abstracted compute method
+  
+  ##
+  # This is a default mixer type that will handle normal
+  # mixer capabilities. It will make use of the +BaseMixer+
+  # setters and getters for the volume, handle general
+  # muting operations, and store data that was previously
+  # loaded into the original +VolumeCtl::Mixer+
+  # (now +AlsaCore::BaseMixer+) class.
+  class DefMixer < AlsaCore::BaseMixer
+    ##
+    # 1. List of channels for the mixer object
+    # 2. List of volume states, used for muting and unmuting
+    attr_reader :channels, :mute_state
+    
+    ##
+    # The +DefMixer+ constructor takes no arguments.
+    # 
+    # It gets the pointers to the +mixer->handle+ and
+    # +mixer->element+ objects in the wrapped +BaseMixer+
+    # class in the C code, utilizing the protected init method.
+    # 
+    # It then clears up the instance variables.
+    def initialize
+      pro_initialize # Call the hidden, protected constructor
+      reset # Reset/initialize instance variables
+    end # end constructor
+    
+    ##
+    # Reset the variables (in case reloading mixer).
+    # 
+    # +reload+ sets the +@mute_state+ and +@channels+
+    # to +nil+, so the mixer does not try to access
+    # invalid data. 
+    def reset() @mute_state = @channels = nil end
+    
+    ##
+    # Connect to the current mixer and enumerate
+    # the channels. See: +enum+ for more information.
+    def connect
+      pro_connect("default", "Master") 
+      enum
+    end # End connect/enum
+    
+    ##
+    # Disconnect from the mixer. You should call this,
+    # when you are done using it, so that there's less of a
+    # chance of errors with GC.
+    def disconnect()
+      pro_disconnect # Disconnect the mixer
+      reset # Reset the instance variables
+    end
+    alias :close :disconnect # End disconnect method and aliases
+    
+    ##
+    # Enumerate the channels.
+    # 
+    # Will return the channels from the underlying +BaseMixer+,
+    # but it is unlikely that they need to be processed,
+    # so the return value can usually be disregarded,
+    # unless it is +nil+, which means it failed.
+    def enum() @channels = pro_enum end
+    
+    ##
+    # Get the volumes from a channel.
+    # 
+    # +c_vget+ takes as an argument a single number,
+    # used to identify the channel the mixer should find
+    # the volume for.
+    # 
+    # = Example
+    #   
+    #   [mixer].c_vget 0 -> 
+    #       {:name=>"Front Left", :max=>65536, :min=>0, :volume=>32768, :percent=>50}
+    def c_vget(channel) pro_cvolume_get(channel) end
+    alias :c_volume :c_vget
+    
+    ##
+    # Get all the volumes and return them as
+    # a clean hash.
+    # 
+    # +vget+, alias +volume+, returns a has with ALL the
+    # volumes by channel number/ID, listed with the following fields:
+    # 
+    # 1. +:name+ -- the name of the channel, such as "Front Left"
+    # 2. +:max+ -- the maximum volume allowed for the channel (probably 65_536)
+    # 3. +:min+ -- the minimum volumes allowed for the channel (usually 0)
+    # 4. +:volume+ -- the current volume as a C +long+
+    # 5. +:percent+ -- the current volume as a percent of max
+    # 
+    # This method takes no arguments and returns a hash.
+    def vget
+      volumes = Hash.new
+      if @channels then # @channels is nil, if not enumerated and will raise errors
+        @channels.each do |k,v|
+          cv = c_vget(k) # Get volume for each channel
+          volumes[k] = cv
+        end # If no channels, print an error to STDERR
+      else $stderr.puts "ERROR: No channels detected. Is mixer connected ('.connect')?" end
+      volumes # Return volumes, unless
+    end 
+    alias :volume :vget # End getter of volumes
+    
+    ##
+    # Set a single channel's volume.
+    # 
+    # Takes as args, +channel (Int)+, +perc_change (Int)+
+    # (percent to change), and +type_change+ (the direction of the 
+    # volume adjustment). +type_change+ is optional and defaults to +nil+.
+    # 
+    # Returns the value of +c_vget+ for the same channel.
+    # 
+    # = Example
+    #   
+    #   [mixer].c_vget 0, 10, :up -> 
+    #       {:name=>"Front Left", :max=>65536, :min=>0, :volume=>32768, :percent=>50}
+    #       
+    # = Example
+    #   
+    #   [mixer].c_vget 0, 10 -> 
+    #       {:name=>"Front Left", :max=>65536, :min=>0, :volume=>32768, :percent=>50}
+    def c_vset(channel, perc_change, type_change=nil)
+      curr = c_vget(channel) # curr must not be nil to continue
+      if curr and (Integer === channel) and (Integer === perc_change) then
+        adjustment = AlsaCtl.compute(curr[:min], curr[:max],
+          curr[:volume], perc_change, type_change)
+        pro_cvolume_set(channel, adjustment)
+      else false end
+    end # End individual channel volume setter
+    
+    ##
+    # Set all the volumes.
+    # 
+    # This is a bypass method. ALSA offers the function,
+    # +snd_mixer_selem_set_playback_volume_all+, which allows us to
+    # shorthand +c_vset+ for every single channel in an iteration loop.
+    # 
+    # Takes only 2 arguments, +perc_change+, and +type_change+, of which
+    # +type_change+ is also optional and defaults to +nil+.
+    # 
+    # Returns the same values as +volume+ / +vget+.
+    # 
+    # This method uses the 0, default channel, usually "Front Left", as
+    # the basis from which to set the volume.
+    # 
+    # Aliased to +set_volume+, as well.
+    # 
+    # = Example
+    #   
+    #   [mixer].vset 100 -> Sets all channels to volume 100%
+    #   
+    # = Example
+    #   
+    #   [mixer].vset 40, :up -> Increases all channels by 40% (up to +:max+)
+    def vset(perc_change, type_change=nil)
+      curr = c_vget(0) # Get the default/lowest channel
+      if curr and (Integer === perc_change) then
+        adjustment = AlsaCtl.compute(curr[:min], curr[:max],
+          curr[:volume], perc_change, type_change)
+        pro_volume_set(adjustment)
+      else false end
+    end 
+    alias :set_volume :vset # End setter for all volumes
+    
+    ##
+    # Mute the mixer.
+    # 
+    # Stores the current values of each channel as a hash in
+    # +@mute_state+. Then uses +vset+ to set all channels to 0%.
+    # 
+    # Returns true on success, or an error message from inside the C code.
+    # 
+    # = Example
+    #   
+    #   [mixer].mute -> true
+    def mute
+      @mute_state = {}
+      volume.each do |idx, v|
+        @mute_state[idx] = v[:percent]
+      end
+      vset(0, nil)
+    end # End mute
+    
+    ##
+    # Unmute the mixer.
+    # 
+    # Checks if +@mute_states+ is empty. If not, uses +c_vset+ to
+    # return all channels to their previous state. Only works, if the
+    # mixer was not closed, beforehand.
+    # 
+    # ALWAYS returns an empty hash, +{}+, so the result can be
+    # ignored. It is just the output of +@mute_state.clear+.
+    # 
+    # = Example
+    #   
+    #   [mixer].unmute -> {}
+    def unmute
+      if !@mute_state.empty? then
+        @mute_state.each do |idx, v|
+          c_vset(idx, v, nil)
+        end
+      end
+      @mute_state.clear
+    end # End unmute
+  end # End DefMixer class
+end # End AlsaCtl module

data/lib/alsactl/version.rb

@@ -0,0 +1,10 @@
+# lib/alsactl/version.rb
+
+##
+# Current version of AlsaCtl
+module AlsaCtl
+  ##
+  # Current version -- I'm only documenting this, so
+  # +rdoc+ doesn't complain.
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: alsactl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Edelweiss
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-05-09 00:00:00.000000000 Z
+dependencies: []
+description: |
+  ALSA wrapper in Ruby, utilizing a purely-abstract C-Ruby API backend
+  and a pure Ruby middleware with extensibility.
+email: 
+executables: []
+extensions:
+- ext/alsacore/extconf.rb
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+- LICENSE.txt
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/alsacore/extconf.rb
+- lib/alsacore/alsacore.so
+- lib/alsactl.rb
+- lib/alsactl/mixers.rb
+- lib/alsactl/version.rb
+homepage: https://github.com/KleineEdelweiss/alsactl_rb
+licenses:
+- LGPL-3.0
+metadata:
+  homepage_uri: https://github.com/KleineEdelweiss/alsactl_rb
+  source_code_uri: https://github.com/KleineEdelweiss/alsactl_rb
+  changelog_uri: https://github.com/KleineEdelweiss/alsactl_rb/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/KleineEdelweiss/alsactl_rb/issues
+post_install_message: 
+rdoc_options:
+- "--title"
+- AlsaCtl -- ALSA wrapper in the C-Ruby API
+- "--main"
+- README.md
+- "--exclude"
+- Makefile
+- "--exclude"
+- Rakefile
+- "--exclude"
+- Gemfile
+- "--exclude"
+- alsactl.gemspec
+- "--exclude"
+- rdoc.sh
+- "--line-numbers"
+- "--inline-source"
+- "--quiet"
+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.2.5
+signing_key: 
+specification_version: 4
+summary: ALSA wrapper in the C-Ruby API
+test_files: []