ffmprb 0.7.0 → 0.7.3

data/lib/ffmprb/process/output.rb

@@ -4,7 +4,7 @@ module Ffmprb
 
     class Output
 
-      def initialize(io, only: nil, resolution: Ffmprb::QVGA, fps: 30)
+      def initialize(io, only:, resolution:, fps:)
         @io = resolve(io)
         @channels = [*only]
         @channels = nil  if @channels.empty?
@@ -14,10 +14,9 @@ module Ffmprb
 
       # XXX This method is exceptionally long at the moment. This is not too grand.
       # However, structuring the code should be undertaken with care, as not to harm the composition clarity.
-      def options(process)
-        # XXX TODO manage stream labels through process
-        raise Error, "Nothing to roll..."  if @reels.select(&:reel).empty?
-        raise Error, "Supporting just full_screen for now, sorry."  unless @reels.all?(&:full_screen?)
+      def options_for(process)  # NOTE process is not thread-safe (nothing actually is), so must not share it with another thread
+        fail Error, "Nothing to roll..."  unless @reels
+        fail Error, "Supporting just full_screen for now, sorry."  unless @reels.all?(&:full_screen?)
 
         filters = []
 
@@ -38,15 +37,15 @@ module Ffmprb
             # NOTE Image-Scaling & Image-Padding to match the target resolution
             # XXX full screen only (see exception above)
 
-            filters +=
-              curr_reel.reel.filters_for(lbl_aux, process: process,
-                video: channel?(:video), audio: channel?(:audio))
-            filters +=
-              Filter.scale_pad_fps(target_width, target_height, target_fps, "#{lbl_aux}:v", "#{lbl}:v")  if
-              channel?(:video)
-            filters +=
-              Filter.anull("#{lbl_aux}:a", "#{lbl}:a")  if
-              channel?(:audio)
+            filters.concat(  # XXX an opportunity for optimisation through passing the actual channel options
+              curr_reel.reel.filters_for lbl_aux, process: process, output: self, video: channel?(:video), audio: channel?(:audio)
+            )
+            filters.concat(
+              Filter.scale_pad_fps target_width, target_height, target_fps, "#{lbl_aux}:v", "#{lbl}:v"
+            )  if channel?(:video)
+            filters.concat(
+              Filter.anull "#{lbl_aux}:a", "#{lbl}:a"
+            )  if channel?(:audio)
           end
 
           trim_prev_at = curr_reel.after || (curr_reel.transition && 0)
@@ -59,22 +58,22 @@ module Ffmprb
 
             lbl_pad = "bl#{prev_lbl}#{i}"
             # NOTE generously padding the previous segment to support for all the cases
-            filters +=
-              Filter.black_source(trim_prev_at + curr_reel.transition_length, target_resolution, target_fps, "#{lbl_pad}:v")  if
-              channel?(:video)
-            filters +=
-              Filter.silent_source(trim_prev_at + curr_reel.transition_length, "#{lbl_pad}:a")  if
-              channel?(:audio)
+            filters.concat(
+              Filter.blank_source trim_prev_at + curr_reel.transition_length, target_resolution, target_fps, "#{lbl_pad}:v"
+            )  if channel?(:video)
+            filters.concat(
+              Filter.silent_source trim_prev_at + curr_reel.transition_length, "#{lbl_pad}:a"
+            )  if channel?(:audio)
 
             if prev_lbl
               lbl_aux = lbl_pad
               lbl_pad = "pd#{prev_lbl}#{i}"
-              filters +=
-                Filter.concat_v(["#{prev_lbl}:v", "#{lbl_aux}:v"], "#{lbl_pad}:v")  if
-                channel?(:video)
-              filters +=
-                Filter.concat_a(["#{prev_lbl}:a", "#{lbl_aux}:a"], "#{lbl_pad}:a")  if
-                channel?(:audio)
+              filters.concat(
+                Filter.concat_v ["#{prev_lbl}:v", "#{lbl_aux}:v"], "#{lbl_pad}:v"
+              )  if channel?(:video)
+              filters.concat(
+                Filter.concat_a ["#{prev_lbl}:a", "#{lbl_aux}:a"], "#{lbl_pad}:a"
+              )  if channel?(:audio)
             end
 
             if curr_reel.transition
@@ -82,12 +81,12 @@ module Ffmprb
               # NOTE Split the previous segment for transition
 
               if trim_prev_at > 0
-                filters +=
-                  Filter.split("#{lbl_pad}:v", ["#{lbl_pad}a:v", "#{lbl_pad}b:v"])  if
-                  channel?(:video)
-                filters +=
-                  Filter.asplit("#{lbl_pad}:a", ["#{lbl_pad}a:a", "#{lbl_pad}b:a"])  if
-                  channel?(:audio)
+                filters.concat(
+                  Filter.split "#{lbl_pad}:v", ["#{lbl_pad}a:v", "#{lbl_pad}b:v"]
+                )  if channel?(:video)
+                filters.concat(
+                  Filter.asplit "#{lbl_pad}:a", ["#{lbl_pad}a:a", "#{lbl_pad}b:a"]
+                )  if channel?(:audio)
                 lbl_pad, lbl_pad_ = "#{lbl_pad}a", "#{lbl_pad}b"
               else
                 lbl_pad, lbl_pad_ = nil, lbl_pad
@@ -100,12 +99,12 @@ module Ffmprb
 
               new_prev_lbl = "tm#{prev_lbl}#{i}a"
 
-              filters +=
-                Filter.trim(0, trim_prev_at, "#{lbl_pad}:v", "#{new_prev_lbl}:v")  if
-                channel?(:video)
-              filters +=
-                Filter.atrim(0, trim_prev_at, "#{lbl_pad}:a", "#{new_prev_lbl}:a")  if
-                channel?(:audio)
+              filters.concat(
+                Filter.trim 0, trim_prev_at, "#{lbl_pad}:v", "#{new_prev_lbl}:v"
+              )  if channel?(:video)
+              filters.concat(
+                Filter.atrim 0, trim_prev_at, "#{lbl_pad}:a", "#{new_prev_lbl}:a"
+              )  if channel?(:audio)
 
               segments << new_prev_lbl
               Ffmprb.logger.debug "Concatting segments: #{new_prev_lbl} pushed"
@@ -119,22 +118,23 @@ module Ffmprb
               lbl_reel = "tn#{i}"
               if !lbl  # no reel
                 lbl_aux = "bk#{i}"
-                filters +=
-                  Filter.black_source(curr_reel.transition_length, target_resolution, target_fps, "#{lbl_aux}:v")  if
-                  channel?(:video)
-                filters +=
-                  Filter.silent_source(curr_reel.transition_length, "#{lbl_aux}:a")  if
-                  channel?(:audio)
+                filters.concat(
+                  Filter.blank_source curr_reel.transition_length, target_resolution, channel(:video).fps, "#{lbl_aux}:v"
+                )  if channel?(:video)
+                filters.concat(
+                  Filter.silent_source curr_reel.transition_length, "#{lbl_aux}:a"
+                )  if channel?(:audio)
               end  # NOTE else hope lbl is long enough for the transition
-              filters +=
-                Filter.trim(trim_prev_at, trim_prev_at + curr_reel.transition_length, "#{lbl_pad_}:v", "#{lbl_end1}:v")  if
-                channel?(:video)
-              filters +=
-                Filter.atrim(trim_prev_at, trim_prev_at + curr_reel.transition_length, "#{lbl_pad_}:a", "#{lbl_end1}:a")  if
-                channel?(:audio)
-              filters +=
-                Filter.transition_av(curr_reel.transition, target_resolution, target_fps, [lbl_end1, lbl || lbl_aux], lbl_reel,
-                  video: channel?(:video), audio: channel?(:audio))
+              filters.concat(
+                Filter.trim trim_prev_at, trim_prev_at + curr_reel.transition_length, "#{lbl_pad_}:v", "#{lbl_end1}:v"
+              )  if channel?(:video)
+              filters.concat(
+                Filter.atrim trim_prev_at, trim_prev_at + curr_reel.transition_length, "#{lbl_pad_}:a", "#{lbl_end1}:a"
+              )  if channel?(:audio)
+              filters.concat(
+                Filter.transition_av curr_reel.transition, target_resolution, target_fps, [lbl_end1, lbl || lbl_aux], lbl_reel,
+                  video: channel?(:video), audio: channel?(:audio)
+              )
               lbl = lbl_reel
             end
 
@@ -147,37 +147,38 @@ module Ffmprb
 
         lbl_out = 'oo'
 
-        filters +=
-          Filter.concat_v(segments.map{|s| "#{s}:v"}, "#{lbl_out}:v")  if channel?(:video)
-        filters +=
-          Filter.concat_a(segments.map{|s| "#{s}:a"}, "#{lbl_out}:a")  if channel?(:audio)
+        filters.concat(
+          Filter.concat_v segments.map{|s| "#{s}:v"}, "#{lbl_out}:v"
+        )  if channel?(:video)
+        filters.concat(
+          Filter.concat_a segments.map{|s| "#{s}:a"}, "#{lbl_out}:a"
+        )  if channel?(:audio)
 
         # Overlays
 
         # NOTE in-process overlays first
 
         @overlays.to_a.each_with_index do |over_reel, i|
+          next  if over_reel.duck  # XXX this is currently a single case of multi-process... process
 
-          # XXX this is currently a single case of multi-process... process
-          unless over_reel.duck
-            raise Error, "Video overlays are not implemented just yet, sorry..."  if over_reel.reel.channel?(:video)
-
-            # Audio overlaying
+          fail Error, "Video overlays are not implemented just yet, sorry..."  if over_reel.reel.channel?(:video)
 
-            lbl_nxt = "oo#{i}"
+          # Audio overlaying
 
-            lbl_over = "ol#{i}"
-            filters +=
-              over_reel.reel.filters_for(lbl_over, process: process)  # NOTE audio only, see above
+          lbl_nxt = "oo#{i}"
 
-            filters +=
-              Filter.copy("#{lbl_out}:v", "#{lbl_nxt}:v")  if channel?(:video)
-            filters +=
-              Filter.amix_to_first(["#{lbl_out}:a", "#{lbl_over}:a"], "#{lbl_nxt}:a")  if channel?(:audio)
-
-            lbl_out = lbl_nxt
-          end
+          lbl_over = "ol#{i}"
+          filters.concat(  # NOTE audio only, see above
+            over_reel.reel.filters_for lbl_over, process: process, output: self
+          )
+          filters.concat(
+            Filter.copy "#{lbl_out}:v", "#{lbl_nxt}:v"
+          )  if channel?(:video)
+          filters.concat(
+            Filter.amix_to_first_same_volume ["#{lbl_out}:a", "#{lbl_over}:a"], "#{lbl_nxt}:a"
+          )  if channel?(:audio)
 
+          lbl_out = lbl_nxt
         end
 
         # NOTE multi-process overlays last
@@ -191,12 +192,12 @@ module Ffmprb
 
           # XXX this is currently a single case of multi-process... process
           if over_reel.duck
-            raise Error, "Don't know how to duck video... yet"  if over_reel.duck != :audio
+            fail Error, "Don't know how to duck video... yet"  if over_reel.duck != :audio
 
             # So ducking just audio here, ye?
 
             main_a_o = channel_lbl_ios["#{lbl_out}:a"]
-            raise Error, "Main output does not contain audio to duck"  unless main_a_o
+            fail Error, "Main output does not contain audio to duck"  unless main_a_o
             # XXX#181845 must really seperate channels for streaming (e.g. mp4 wouldn't stream through the fifo)
             main_a_inter_o = File.temp_fifo(main_a_o.extname)
             channel_lbl_ios.each do |channel_lbl, io|
@@ -204,27 +205,25 @@ module Ffmprb
             end
             Ffmprb.logger.debug "Re-routed the main audio output (#{main_a_inter_o.path}->...->#{main_a_o.path}) through the process of audio ducking"
 
-            overlay_io = File.buffered_fifo(Process.intermediate_channel_extname :audio)
-            process.threaded overlay_io.thr
+            overlay_i, overlay_o = File.threaded_buffered_fifo(Process.intermediate_channel_extname :audio)
             lbl_over = "ol#{i}"
-            filters +=
-              over_reel.reel.filters_for(lbl_over, process: process, video: false, audio: true)
-            channel_lbl_ios["#{lbl_over}:a"] = overlay_io.in
-            Ffmprb.logger.debug "Routed and buffering an auxiliary output fifos (#{overlay_io.in.path}>#{overlay_io.out.path}) for overlay"
+            filters.concat(
+              over_reel.reel.filters_for lbl_over, process: process, output: self, video: false, audio: true
+            )
+            channel_lbl_ios["#{lbl_over}:a"] = overlay_i
+            Ffmprb.logger.debug "Routed and buffering an auxiliary output fifos (#{overlay_i.path}>#{overlay_o.path}) for overlay"
 
-            inter_io = File.buffered_fifo(main_a_inter_o.extname)
-            process.threaded inter_io.thr
-            Ffmprb.logger.debug "Allocated fifos to buffer media (#{inter_io.in.path}>#{inter_io.out.path}) while finding silence"
+            inter_i, inter_o = File.threaded_buffered_fifo(main_a_inter_o.extname)
+            Ffmprb.logger.debug "Allocated fifos to buffer media (#{inter_i.path}>#{inter_o.path}) while finding silence"
 
-            thr = Util::Thread.new "audio ducking" do
-              silence = Ffmprb.find_silence(main_a_inter_o, inter_io.in)
+            Util::Thread.new "audio ducking" do
+              silence = Ffmprb.find_silence(main_a_inter_o, inter_i)
 
               Ffmprb.logger.debug "Audio ducking with silence: [#{silence.map{|s| "#{s.start_at}-#{s.end_at}"}.join ', '}]"
 
-              Process.duck_audio inter_io.out, overlay_io.out, silence, main_a_o,
+              Process.duck_audio inter_o, overlay_o, silence, main_a_o,
                 video: (channel?(:video)? {resolution: target_resolution, fps: target_fps}: false)
             end
-            process.threaded thr
           end
 
         end
@@ -238,6 +237,8 @@ module Ffmprb
           io_channel_lbls.each do |io, channel_lbls|
             channel_lbls.each do |channel_lbl|
               options << '-map' << "[#{channel_lbl}]"
+              # XXX temporary patchwork
+              options << '-c:a' << 'libmp3lame'  if channel_lbl =~ /:a$/
             end
             options << io.path
           end
@@ -245,39 +246,36 @@ module Ffmprb
         end
       end
 
-      def cut(
+      def roll(
+        reel,
+        onto: :full_screen,
         after: nil,
         transition: nil
       )
-        raise Error, "Nothing to cut yet..."  if @reels.empty? || @reels.last.reel.nil?
+        fail Error, "Nothing to roll..."  unless reel
+        fail Error, "Supporting :transition with :after only at the moment, sorry."  unless
+          !transition || after || @reels.to_a.empty?
 
-        add_reel nil, after, transition, @reels.last.full_screen?
+        add_reel reel, after, transition, (onto == :full_screen)
       end
+      alias :lay :roll
 
       def overlay(
         reel,
         at: 0,
+        transition: nil,
         duck: nil
       )
-        raise Error, "Nothing to overlay..."  unless reel
-        raise Error, "Nothing to lay over yet..."  if @reels.to_a.empty?
-        raise Error, "Ducking overlays should come last... for now"  if !duck && @overlays.to_a.last && @overlays.to_a.last.duck
+        fail Error, "Nothing to overlay..."  unless reel
+        fail Error, "Nothing to lay over yet..."  if @reels.to_a.empty?
+        fail Error, "Ducking overlays should come last... for now"  if !duck && @overlays.to_a.last && @overlays.to_a.last.duck
 
         (@overlays ||= []) <<
           OpenStruct.new(reel: reel, at: at, duck: duck)
       end
 
-      def roll(
-        reel,
-        onto: :full_screen,
-        after: nil,
-        transition: nil
-      )
-        raise Error, "Nothing to roll..."  unless reel
-        raise Error, "Supporting :transition with :after only at the moment, sorry."  unless
-          !transition || after || @reels.to_a.empty?
-
-        add_reel reel, after, transition, (onto == :full_screen)
+      def channel?(medium)
+        @channels.include?(medium) && @io.channel?(medium) && reels_channel?(medium)
       end
 
       def channel?(medium, force=false)
@@ -287,7 +285,7 @@ module Ffmprb
           reels_channel?(medium)
       end
 
-      protected
+      # XXX TMP protected
 
       def resolve(io)
         return io  unless io.is_a? String
@@ -295,22 +293,22 @@ module Ffmprb
         case io
         when /^\/\w/
           File.create(io).tap do |file|
-            Ffmprb.logger.warn "Output file exists (#{file.path}), will overwrite"  if file.exist?
+            Ffmprb.logger.warn "Output file exists (#{file.path}), will probably overwrite"  if file.exist?
           end
         else
-          raise Error, "Cannot resolve output: #{io}"
+          fail Error, "Cannot resolve output: #{io}"
         end
       end
 
-      private
+      # XXX TMP private
 
       def reels_channel?(medium)
         @reels.to_a.all?{|r| !r.reel || r.reel.channel?(medium)}
       end
 
       def add_reel(reel, after, transition, full_screen)
-        raise Error, "No time to roll..."  if after && after.to_f <= 0
-        raise Error, "Partial (not coming last in process) overlays are currently unsupported, sorry."  unless @overlays.to_a.empty?
+        fail Error, "No time to roll..."  if after && after.to_f <= 0
+        fail Error, "Partial (not coming last in process) overlays are currently unsupported, sorry."  unless @overlays.to_a.empty?
 
         # NOTE limited functionality (see exception in Filter.transition_av): transition = {effect => duration}
         transition_length = transition.to_h.max_by{|k,v| v}.to_a.last.to_f

data/lib/ffmprb/process.rb

@@ -1,14 +1,13 @@
-require 'ffmprb/process/input'
-require 'ffmprb/process/output'
-
 module Ffmprb
 
   class Process
 
     class << self
 
-      attr_accessor :duck_audio_hi, :duck_audio_lo
-      attr_accessor :duck_audio_silent_min_sec, :duck_audio_transition_sec
+      attr_accessor :duck_audio_volume_hi, :duck_audio_volume_lo
+      attr_accessor :duck_audio_silent_min, :duck_audio_transition_length
+
+      attr_accessor :timeout
 
       def intermediate_channel_extname(*media)
         if media == [:video]
@@ -18,31 +17,38 @@ module Ffmprb
         elsif media.sort == [:audio, :video]
           '.flv'
         else
-          raise Error, "I don't know how to channel [#{media.join ', '}]"
+          fail Error, "I don't know how to channel [#{media.join ', '}]"
         end
       end
 
-      def duck_audio(av_main_i, a_overlay_i, silence, av_main_o, video: {resolution: Ffmprb::QVGA, fps: 30})
+      def duck_audio(av_main_i, a_overlay_i, silence, av_main_o,
+        volume_lo: duck_audio_volume_lo, volume_hi: duck_audio_volume_hi,
+        silent_min: duck_audio_silent_min, transition_length: duck_audio_transition_length,
+        video: {resolution: Ffmprb::CGA, fps: 30}  # XXX temporary
+        )
         Ffmprb.process(av_main_i, a_overlay_i, silence, av_main_o) do |main_input, overlay_input, duck_data, main_output|
 
           in_main = input(main_input, **(video ? {} : {only: :audio}))
           in_over = input(overlay_input, only: :audio)
           output(main_output, **(video ? {resolution: video[:resolution], fps: video[:fps]} : {})) do
             roll in_main
-            ducked_overlay_volume = {0.0 => Process.duck_audio_lo}
+
+            ducked_overlay_volume = {0.0 => volume_lo}
             duck_data.each do |silent|
-              next  if silent.end_at && silent.start_at && (silent.end_at - silent.start_at) < Process.duck_audio_silent_min_sec
+              next  if silent.end_at && silent.start_at && (silent.end_at - silent.start_at) < silent_min
 
               ducked_overlay_volume.merge!(
-                [silent.start_at - Process.duck_audio_transition_sec/2, 0.0].max => Process.duck_audio_lo,
-                (silent.start_at + Process.duck_audio_transition_sec/2) => Process.duck_audio_hi
+                [silent.start_at - transition_length/2, 0.0].max => volume_lo,
+                (silent.start_at + transition_length/2) => volume_hi
               )  if silent.start_at
+
               ducked_overlay_volume.merge!(
-                [silent.end_at - Process.duck_audio_transition_sec/2, 0.0].max => Process.duck_audio_hi,
-                (silent.end_at + Process.duck_audio_transition_sec/2) => Process.duck_audio_lo
+                [silent.end_at - transition_length/2, 0.0].max => volume_hi,
+                (silent.end_at + transition_length/2) => volume_lo
               )  if silent.end_at
             end
             overlay in_over.volume ducked_overlay_volume
+
             Ffmprb.logger.debug "Ducking audio with volumes: {#{ducked_overlay_volume.map{|t,v| "#{t}: #{v}"}.join ', '}}"
           end
 
@@ -51,8 +57,11 @@ module Ffmprb
 
     end
 
-    def initialize(*args, &blk)
+    attr_reader :timeout
+
+    def initialize(*args, **opts, &blk)
       @inputs = []
+      @timeout = opts[:timeout] || self.class.timeout
     end
 
     def input(io, only: nil)
@@ -61,17 +70,25 @@ module Ffmprb
       end
     end
 
-    def output(io, only: nil, resolution: Ffmprb::QVGA, fps: 30, &blk)
-      raise Error, "Just one output for now, sorry."  if @output
+    def output(io, only: nil, resolution: Ffmprb::CGA, fps: 30, &blk)
+      fail Error, "Just one output for now, sorry."  if @output
 
-      @output = Output.new(io, only: only, resolution: resolution).tap do |out|
+      @output = Output.new(io, only: only, resolution: resolution, fps: fps).tap do |out|
         out.instance_exec &blk
       end
     end
 
-    def run
-      Util.ffmpeg *command
-      @threaded.to_a.each &:join
+    # NOTE the one and the only entry-point processing function which spawns threads etc
+    def run(limit: nil)  # (async: false)
+      # NOTE this is both for the future async: option and according to
+      # the threading policy (a parent death will be noticed and handled by children)
+      thr = Util::Thread.new do
+        # NOTE yes, an exception can occur anytime, and we'll just die, it's ok, see above
+        Util.ffmpeg(*command, limit: limit, timeout: timeout).tap do |res|  # XXX just to return something
+          Util::Thread.join_children! limit, timeout: timeout
+        end
+      end
+      thr.value  if thr.join limit  # NOTE should not block for more than limit
     end
 
     def [](obj)
@@ -81,11 +98,6 @@ module Ffmprb
       end
     end
 
-    # TODO deserves a better solution
-    def threaded(thr)
-      (@threaded ||= []) << thr
-    end
-
     private
 
     def command
@@ -97,7 +109,7 @@ module Ffmprb
     end
 
     def output_options
-      @output.options self
+      @output.options_for self
     end
 
   end

data/lib/ffmprb/util/thread.rb

@@ -5,19 +5,101 @@ module Ffmprb
     # NOTE doesn't have specs (and not too proud about it)
     class Thread < ::Thread
 
+      class Error < StandardError; end
+      class ParentError < Error; end
+
+      class << self
+
+        attr_accessor :timeout
+
+        def timeout_or_live(limit=nil, log: "while doing this", timeout: self.timeout, &blk)
+          started_at = Time.now
+          tries = 0
+          logged_tries = 0
+          begin
+            tries += 1
+            time = Time.now - started_at
+            fail TimeLimitError  if limit && time > limit
+            Timeout.timeout timeout do
+              blk.call time
+            end
+          rescue Timeout::Error
+            if tries > 2 * logged_tries
+              Ffmprb.logger.info "A little bit of timeout #{log.respond_to?(:call)? log.call : log} (##{tries})"
+              logged_tries = tries
+            end
+            current.live!
+            retry
+          end
+        end
+
+        def join_children!(limit=nil, timeout: self.timeout)
+          Thread.current.join_children! limit, timeout: timeout
+        end
+
+      end
+
+      attr_reader :name
+
       def initialize(name="some", &blk)
+        @name = name
+        @parent = Thread.current
+        @live_children = []
+        @children_mon = Monitor.new
+        @dead_children_q = Queue.new
+        Ffmprb.logger.debug "about to launch #{name}"
+        sync_q = Queue.new
         super() do
+          @parent.child_lives self  if @parent.respond_to? :child_lives
+          sync_q.enq :ok
+          Ffmprb.logger.debug "#{name} thread launched"
           begin
-            Ffmprb.logger.debug "#{name} thread launched"
-            blk.call
-            Ffmprb.logger.debug "#{name} thread done"
+            blk.call.tap do
+              Ffmprb.logger.debug "#{name} thread done"
+            end
           rescue Exception
-            Ffmprb.logger.warn "#{$!.class} caught in a #{name} thread (hidden): #{$!.message}\nBacktrace:\n\t#{$!.backtrace.join("\n\t")}"
+            Ffmprb.logger.warn "#{$!.class} raised in #{name} thread: #{$!.message}\nBacktrace:\n\t#{$!.backtrace.join("\n\t")}"
             cause = $!
             Ffmprb.logger.warn "...caused by #{cause.class}: #{cause.message}\nBacktrace:\n\t#{cause.backtrace.join("\n\t")}" while
               cause = cause.cause
-            raise
+            fail $!  # XXX I have no idea why I need to give it `$!` -- the docs say I need not
+          ensure
+            @parent.child_dies self  if @parent.respond_to? :child_dies
+          end
+        end
+        sync_q.deq
+      end
+
+      # XXX protected: none of these methods should be called by a user code, the only public methods are above
+
+      def live!
+        fail ParentError  if @parent.status.nil?
+      end
+
+      def child_lives(thr)
+        @children_mon.synchronize do
+          Ffmprb.logger.debug "picking up #{thr.name} thread"
+          @live_children << thr
+        end
+      end
+
+      def child_dies(thr)
+        @children_mon.synchronize do
+          Ffmprb.logger.debug "releasing #{thr.name} thread"
+          @dead_children_q.enq thr
+          fail "System Error"  unless @live_children.delete thr
+        end
+      end
+
+      def join_children!(limit=nil, timeout: self.class.timeout)
+        timeout = [timeout, limit].compact.min
+        Ffmprb.logger.debug "joining threads: #{@live_children.size} live, #{@dead_children_q.size} dead"
+        until @live_children.empty? && @dead_children_q.empty?
+          thr = self.class.timeout_or_live limit, log: "joining threads: #{@live_children.size} live, #{@dead_children_q.size} dead", timeout: timeout do
+            @dead_children_q.deq
           end
+          Ffmprb.logger.debug "joining the late #{thr.name} thread"
+          fail "System Error"  unless thr.join(timeout)  # NOTE should not block
         end
       end