tef-animation 0.1.0 → 0.1.1

data/lib/tef/ProgramSelection/SequenceCollection.rb

@@ -4,9 +4,22 @@ require_relative 'ProgramID.rb'
 
 module TEF
 	module ProgramSelection
+		# Sheet Sequence collection
+		#
+		# This class is meant as a convenient container for
+		# {Sequencing::Sheet}s. It automatically registers
+		# used {ID}s with the used {Selector}, and is also
+		# responsible for easily registering {ProgramSheet}s.
 		class SequenceCollection
+			# @return [Hash<ID, Hash>] Options to pass to
+			#  specific sheets when instantiating them.
+			#  Useful when re-using a {Sequencing::Sheet} for
+			#  different programs.
 			attr_reader :sheet_opts
 
+			# @return [SequenceCollection] Last Collection that
+			#  was instantiated. Used by {ProgramSelection} to
+			#  register itself.
 			def self.current_collection
 				@current_collection
 			end
@@ -14,6 +27,26 @@ module TEF
 				@current_collection = n_collection
 			end
 
+			# Initialize a collection.
+			#
+			# The passed {Selector} is used to register Sheet {ID}s, while
+			# the passed {Sequencing::Player} is used to start
+			# playing Sheets when using {#play}
+			#
+			# Will set {SequenceCollection#current_collection} to self
+			#
+			# @example
+			#   sheet_collection = SequenceCollection.new(programs, player);
+			#
+			#   ProgramSheet.new() do |s|
+			#      s.add_key 'hello', ['portal', 'turret']
+			#
+			#      # Write sheet contents here.
+			#      # The ProgramSheet will self-register to the
+			#      # created sheet collection.
+			#   end
+			#
+			#   sheet_collection.play(programs.fetch_string('hello'));
 			def initialize(program_selector, sequence_runner)
 				@program_selector = program_selector
 				@sequence_runner = sequence_runner
@@ -24,14 +57,36 @@ module TEF
 				self.class.current_collection = self
 			end
 
+			# @return [nil, Sequencing::Sheet, ProgramSheet] Sheet matching
+			#   the given {ID}, or nil.
 			def [](key)
 				@known_programs[key]
 			end
+
+			# Register a given program.
+			#
+			# @param [ID] key {ID} to register the program under.
+			#   Will be registered with the {Selector} passed to the
+			#   constructor.
+			# @param [Sequencing::Sheet, ProgramSheet] n_program New program
+			#   to register.
 			def []=(key, n_program)
 				key = @program_selector.register_ID key
 				@known_programs[key] = n_program
 			end
 
+			# Start playing the {Sequencing::Sheet} matching the given {ID}
+			#
+			# This function will instantiate a new {Sequencing::SheetSequence} if
+			# the registered program was a {ProgramSheet}. It will pass the
+			# {#sheet_opts} matching its ID to the SheetSequence, and will
+			# additionally set the option's :program_key value to the {ID} used
+			# here.
+			# This allows easy re-using of sheets by passing parameters via
+			# the sheet options.
+			#
+			# The created sheet is then passed to {Sequencing::Player#[]=}, using
+			# either {ProgramSheet#program_key} or 'default' as key.
 			def play(key)
 				prog = @known_programs[key]
 				return unless prog
@@ -51,7 +106,14 @@ module TEF
 			end
 		end
 
+		# Convenience class.
+		# Mainly extends {Sequencing::Sheet} with an {#add_key} function, which
+		# self-registers this program under the last created {SequenceCollection}.
 		class ProgramSheet < TEF::Sequencing::Sheet
+
+			# Optional key to use when passing to {Sequencing::Player#[]=}.
+			# Different keys are necessary to not overwrite the previous running
+			# program.
 			attr_accessor :program_key
 
 			def initialize()
@@ -59,16 +121,20 @@ module TEF
 
 				yield(self) if block_given?
 			end
-
-			## TODO Give option to add multiple keys with options-hash
-
-			def add_key(title, groups = [], variation = '.mp3')
+			
+			# Register this sheet under a given key.
+			# Syntax is the same as {Selector#register_ID}, with a default
+			# variant of '.mp3' to comply with the default variant set by
+			# {SoundCollection}.
+			def add_key(title, groups = [], variation = '.mp3', options = nil)
 				prog_collection = SequenceCollection.current_collection
 				raise "No program collection was instantiated yet!" unless prog_collection
 
 				id = ID.new(title, groups, variation)
 
 				prog_collection[id] = self
+
+				prog_collection.sheet_opts[id] = options if options.is_a? Hash
 			end
 		end
 	end

data/lib/tef/ProgramSelection/SoundCollection.rb

@@ -5,11 +5,59 @@ require 'yaml'
 
 module TEF
 	module ProgramSelection
+
+		# Sound-File collection.
+		#
+		# This class is meant as convenient container for sound-filenames.
+		# It will automatically scan the current directory for any file ending
+		# with '.mp3', '.ogg' or '.wav', and will construct a unique {ID} for
+		# it based on the filepath.
+		# Paths can then be retrieved by using {#soundmap}.
+		#
+		# Additionally, it keeps a list of silences, the {#silence_maps}. They
+		# are auto-generated lists of silences or loud sections of the file,
+		# useful for auto-generating programs.
+		# They can be retrieved via {#silence_maps}
+		#
+		# Note that to play a sound, this should be done via
+		# {Sequencing::SheetSequence#play}, to ensure that the sound is killed
+		# in synch with the program.
 		class SoundCollection
+			# @return [Hash<String, Hash<Numeric, Numeric>>] List of noise levels
+			#  for a given file-path. Is in the format { timestamp (in s) => 0 to 1 }
+			#  It is ensured that a 0 is inserted at the beginning and end of the
+			#  sound track, and it is ensured that the hash keys are sorted.
+			#
+			# @see #silences_for
 			attr_reader :silence_maps
+
+			# @return [Hash<ID, String>] Map of {ID}s to matching file-paths
 			attr_reader :soundmap
+
+			# @return [Hash] Config loaded from './sounds/soundconfig.yml'
 			attr_reader :load_config
 
+			# Initialize a SoundCollection
+			#
+			# This will scan the current directory for any sound files. Found
+			# files will auto-generate a ID based on their path, and are
+			# registered with the passed {Selector}.
+			#
+			# Paths are deconstructed as follows:
+			# - The path is split along any '/' or '-'. Each element up to
+			#   the last is taken as a group. The last element in the list
+			#   is taken as title.
+			# - The variant is generated by taking the sequence (-\d+)?\.(mp3|ogg|wav)
+			#   from the end. This means that variants can be specified by appending
+			#   a '-1234' to the title.
+			#
+			# './sounds/portal/announcer-hello-4.mp3' is registered as:
+			#  {Selector#register_ID}('hello', ['sounds', 'portal', 'announcer'], '-4.mp3');
+			#
+			# Also note that a custom config file, {#load_config}, is loaded from
+			#  a YAML file './sounds/soundconfig.yml', if present.
+			# Additionally, the {#silence_maps} are loaded from, and saved to,
+			#  './sounds/silence_maps.yml'
 			def initialize(program_handler)
 				@handler = program_handler
 				@soundmap = {}
@@ -28,11 +76,11 @@ module TEF
 				`find ./`.split("\n").each { |fn| add_file fn };
 
 				File.write('./sounds/silence_maps.yml', YAML.dump(@silence_maps));
-
-				@play_pids = {};
 			end
 
-			def generate_silences(fname)
+			# Internal function. Generates a list
+			# of silences/loud sections with ffmpeg.
+			private def generate_silences(fname)
 				return if @silence_maps[fname]
 
 				ffmpeg_str = `ffmpeg -i #{fname} -af silencedetect=n=0.1:d=0.1 -f null - 2>&1`
@@ -65,6 +113,10 @@ module TEF
 				@silence_maps[fname] = out_event
 			end
 
+			# Add a file to the collection of files.
+			#
+			# Will auto-generate silences and a matching {ID} as described
+			# in {#initialize}.
 			def add_file(fname)
 				rMatch = /^\.\/sounds\/(?<groups>(?:[a-z_]+[\/-])*)(?<title>[a-z_]+)(?<variant>(?:-\d+)?\.(?:ogg|mp3|wav))/.match fname;
 				return unless rMatch;
@@ -81,28 +133,13 @@ module TEF
 				generate_silences fname
 			end
 
+			# @return [Hash<Numeric, Numeric>, nil] The silence map for
+			#  the passed {ID}, or nil if none was found.
+			#
+			# @see #silence_maps
 			def silences_for(key)
 				@silence_maps[@soundmap[key]]
 			end
-
-			def play(id, collection_id = 'default')
-				sound_name = @soundmap[id]
-				return if sound_name.nil?
-
-				collection_id ||= id;
-
-				if old_pid = @play_pids[collection_id]
-					Process.kill('QUIT', old_pid)
-				end
-
-				Thread.new do
-					fork_pid = spawn(*%W{play -q --volume 0.3 #{sound_name}});
-
-					@play_pids[collection_id] = fork_pid;
-					Process.waitpid fork_pid;
-					@play_pids.delete collection_id
-				end
-			end
 		end
 	end
 end

data/lib/tef/Sequencing/BaseSequence.rb

@@ -1,17 +1,50 @@
 
 require_relative 'EventCollector.rb'
 
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
 	module Sequencing
+		# Base sequence class.
+		#
+		# It implements the minium necessary tools to make different Sequences
+		# work together nicely. It's main function is to provide {#append_events},
+		# which is used by a {Player} to fetch the next queued event for execution.
 		class BaseSequence
+			# @return [Numeric] Start time of this sequence, in local time.
+			#  Specifies when to call {#setup}
 			attr_reader :start_time
+			# @return [Numeric, nil] End time of this sequence, in local time.
+			#  Specifies when to call {#teardown}. Can be left as nil for no
+			#  automatic teardown.
 			attr_reader :end_time
 
+			# @return [Numeric, Time] The offset to apply to this Sequence,
+			#  used when converting between local-time and parent-time.
+			#
+			#  This MAY be modified during runtime, though this may cause some
+			#  events to be skipped!
 			attr_reader :offset
+			# @return [Numeric] Slope to apply to this sequence.
+			# @see #offset
 			attr_reader :slope
 
+			# @return [Symbol] State of this Sequence. Mainly used for internal
+			# purposes. Can be:
+			# - :uninitialized (right after construction)
+			# - :running (after having called setup())
+			# - :torn_down (after teardown() was called)
 			attr_reader :state
 
+			# Initialize a BaseSequence.
+			#
+			# @param [Numeric, Time] offset Provide a offset for time-conversion.
+			#  @see #offset
+			# @param [Numeric] slope Provide a slope for time-conversion.
+			#  @see #slope
+			#
+			# @param [Numeric] :start_time Local time to begin playing at.
+			# @param [Numeric] :end_time   Local time to tear down at.
 			def initialize(offset, slope, **options)
 				@start_time ||= options[:start_time] || 0;
 				@end_time   ||= options[:end_time];
@@ -40,6 +73,15 @@ module TEF
 				@opts_hash = nil;
 			end
 
+			# Look for the next possible event that this sequence wants to
+			# execute.
+			# Will ensure that this sequence's {#setup} and {#teardown} blocks
+			# are called at the appropriate time.
+			#
+			# Should only be called by a {Player} or another sequence!
+			#
+			# @note When using BaseSequence as base class, the user
+			#  shall overload {#overload_append_events} rather than this function!
 			def append_events(collector)
 				local_collector = collector.offset_collector(@offset, @slope);
 
@@ -49,7 +91,7 @@ module TEF
 
 				if @state == :uninitialized
 					local_collector.add_event({
-						time: @start_time,
+						time: [@start_time, local_collector.start_time + 0.01].max,
 						code: proc { self.setup() }
 					});
 				end
@@ -61,7 +103,7 @@ module TEF
 				if !@end_time.nil?
 					local_collector.add_event({
 						time: @end_time,
-						code: proc { self.teardown }
+						code: proc { self.teardown() }
 					})
 				end
 			end

data/lib/tef/Sequencing/EventCollector.rb

@@ -1,43 +1,83 @@
 
 require 'xasin_logger'
 
+# TheElectricFursuits module.
+# @see https://github.com/TheElectricFursuits
 module TEF
+	# Program Sequencing module.
+	#
+	# This module contains all components necessary to define how and when
+	# a animation or program will execute. It provides a base class
+	# to define how execution information is passed along between code, as well
+	# as a more user friendly interface to define a fixed sequence of events,
+	# a so called {Sheet}.
+	#
+	# {Sheet}s are designed to be as reuseable as possible,
+	# with dynamic creation to let the same sheet be adapted to different
+	# situations, as well as Sheet and Event nesting that makes it easy to
+	# re-use other {Sheet}s, for example to define segments of a song or
+	# generic beat-segments.
 	module Sequencing
+		# Purely internal class
+		#
+		# Used by {BaseSequence} when fetching the next event from child
+		# sequences. It wraps {EventCollector} and automatically applies
+		# a sequence's offset and slope, converting between the timeframe
+		# of the parent and the child.
+		#
+		# This collector is created in the child, within {BaseSequence#append_events}
 		class OffsetCollector
+			# @return [EventCollector] Top-Level collector
 			attr_reader :parent
 
+			# @return [Time] Offset of the conversion. Used as follows:
+			#   local_time = (Time.at(x) - total_offset) * total_slope
 			attr_reader :total_offset
+			# @return [Numeric] Slope of the time conversion.
+			# @see #total_offset
 			attr_reader :total_slope
 
+			# Initialize a new offset collector.
+			# This should only be done via {EventCollector#offset_collector}!
 			def initialize(parent, total_offset, total_slope)
 				@parent = parent
 				@total_offset = total_offset
 				@total_slope  = total_slope
 			end
 
+			# @param [Time, nil] global_time Time to convert
+			# @return [Numeric, nil] Converted time
 			def convert_to_local(global_time)
 				return nil if global_time.nil?
 
 				(global_time - @total_offset) * @total_slope
 			end
+
+			# @param [Numeric, nil] local_time Time (abstract) to convert back
+			#  into the global frame.
+			# @return [Time, nil] Time (as Time object) of the event
 			def convert_to_global(local_time)
 				return nil if local_time.nil?
 
 				@total_offset + (local_time.to_f / @total_slope)
 			end
 
+			# (see EventCollector#start_time)
 			def start_time
 				convert_to_local @parent.start_time
 			end
 
+			# (see EventCollector#event_time)
 			def event_time
 				convert_to_local @parent.event_time
 			end
 
+			# (see EventCollector#has_events?)
 			def has_events?
 				return @parent.has_events?
 			end
 
+			# (see EventCollector#add_event)
 			def add_event(event)
 				event = event.clone
 
@@ -46,21 +86,36 @@ module TEF
 				@parent.add_event event
 			end
 
+			# (see EventCollector#add_events)
 			def add_events(list)
 				list.each { |event| add_event event }
 			end
 
+			# (see EventCollector#offset_collector)
 			def offset_collector(offset, slope)
 				OffsetCollector.new(@parent, convert_to_global(offset), @total_slope * slope)
 			end
 		end
 
+		# Event Collector class
+		#
+		# This class provides the means to efficiently fetch the next event
+		# from a list of {BaseSequence}s, and is mainly meant for
+		# internal purposes. It is created by {Player}
 		class EventCollector
 			include XasLogger::Mix
 
+			# @return [Time] The Time to start looking for an event.
+			#  Any event earlier than this will be discarded!
 			attr_accessor :start_time
+
+			# @return [nil, Time] The Time of the current event, or nil if
+			#  there is no event. Any event later than this will be
+			#  discarded. Any event equal to this time will be appended to
+			#  {#current_events}
 			attr_reader   :event_time
 
+			# @return [Array<Hash>] List of current events to execute.
 			attr_reader :current_events
 
 			def initialize()
@@ -71,6 +126,12 @@ module TEF
 				init_x_log("Sequence Player")
 			end
 
+			# Internal function to add an event.
+			# The event will be discarded if it is earlier than or equal to
+			# start time, or later than the event time.
+			# It if it is earlier than event time it will set the new event time
+			# and set the event list to [event], else append the event
+			# to the event list.
 			def add_event(event)
 				return if event[:time] <= @start_time
 				return if (!@event_time.nil?) && (event[:time] > @event_time)
@@ -83,10 +144,14 @@ module TEF
 				end
 			end
 
+			# @return [true, false] Were any events found?
 			def has_events?
 				!@current_events.empty?
 			end
 
+			# This function will try to wait until {#event_time}.
+			# If no event was found it will return immediately, and Thread.run()
+			# can be used to prematurely end the wait.
 			def wait_until_event
 				return unless has_events?
 
@@ -101,6 +166,8 @@ module TEF
 				sleep t_diff if t_diff > 0
 			end
 
+			# Wait until the next event and then execute
+			# the code of each event.
 			def execute!
 				return unless has_events?
 
@@ -114,11 +181,18 @@ module TEF
 				restart();
 			end
 
+			# Restart this collector.
+			# Will clear {#current_events} and {#event_time}
 			def restart()
 				@current_events = []
 				@event_time = nil;
 			end
 
+			# Generate a {OffsetCollector}
+			# This is mainly an internal function used by {BaseSequence} to
+			# provide an {OffsetCollector}. It converts between the global time-frame
+			# used by this collector, and the local timeframes of each
+			# sub-sequence.
 			def offset_collector(offset, slope)
 				OffsetCollector.new(self, offset, slope);
 			end