ffmprb 0.7.5 → 0.9.0

data/lib/ffmprb/process/output.rb

@@ -1,24 +1,45 @@
+require 'ostruct'
+
 module Ffmprb
 
   class Process
 
     class Output
 
-      def initialize(io, only:, resolution:, fps:)
+      class << self
+
+        def audio_cmd_options(audio=Process.output_audio_options)
+          audio ||= {}
+          [].tap do |options|
+            options.concat %W[-c:a #{audio[:encoder]}]  if audio[:encoder]
+          end
+        end
+
+      end
+
+      # TODO unique labeling does not justify idx, will be refactored
+      def initialize(io, idx, video:, audio:)
         @io = resolve(io)
-        @channels = [*only]
-        @channels = nil  if @channels.empty?
-        @resolution = resolution
-        @fps = 30
+        @idx = idx
+        @channels = {
+          video: video && @io.channel?(:video) && OpenStruct.new(video),
+          audio: audio && @io.channel?(:audio) && OpenStruct.new(audio)
+        }
+        if channel?(:video)
+          channel(:video).resolution.to_s.split('x').each do |dim|
+            fail Error, "Both dimensions of a resolution must be divisible by 2, sorry about that"  unless dim.to_i % 2 == 0
+          end
+        end
       end
 
       # 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_for(process)  # NOTE process is not thread-safe (nothing actually is), so must not share it with another thread
+      def filters
         fail Error, "Nothing to roll..."  unless @reels
         fail Error, "Supporting just full_screen for now, sorry."  unless @reels.all?(&:full_screen?)
+        return @filters  if @filters
 
-        filters = []
+        @filters = []
 
         # Concatting
         segments = []
@@ -31,24 +52,18 @@ module Ffmprb
 
             # NOTE mapping input to this lbl
 
-            lbl = "rl#{i}"
-            lbl_aux = "sp#{i}"
+            lbl = "o#{@idx}rl#{i}"
 
-            # NOTE Image-Scaling & Image-Padding to match the target resolution
-            # XXX full screen only (see exception above)
+            # NOTE Image-Padding to match the target resolution
+            # TODO full screen only at the moment (see exception above)
 
-            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(
+              curr_reel.reel.filters_for lbl, 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)
+          transition_length = curr_reel.transition ? curr_reel.transition.length : 0
 
           if trim_prev_at
 
@@ -58,20 +73,21 @@ module Ffmprb
 
             lbl_pad = "bl#{prev_lbl}#{i}"
             # NOTE generously padding the previous segment to support for all the cases
-            filters.concat(
-              Filter.blank_source trim_prev_at + curr_reel.transition_length, target_resolution, target_fps, "#{lbl_pad}:v"
+            @filters.concat(
+              Filter.blank_source trim_prev_at + transition_length,
+              channel(:video).resolution, channel(:video).fps, "#{lbl_pad}:v"
             )  if channel?(:video)
-            filters.concat(
-              Filter.silent_source trim_prev_at + curr_reel.transition_length, "#{lbl_pad}:a"
+            @filters.concat(
+              Filter.silent_source trim_prev_at + transition_length, "#{lbl_pad}:a"
             )  if channel?(:audio)
 
             if prev_lbl
               lbl_aux = lbl_pad
               lbl_pad = "pd#{prev_lbl}#{i}"
-              filters.concat(
+              @filters.concat(
                 Filter.concat_v ["#{prev_lbl}:v", "#{lbl_aux}:v"], "#{lbl_pad}:v"
               )  if channel?(:video)
-              filters.concat(
+              @filters.concat(
                 Filter.concat_a ["#{prev_lbl}:a", "#{lbl_aux}:a"], "#{lbl_pad}:a"
               )  if channel?(:audio)
             end
@@ -81,10 +97,10 @@ module Ffmprb
               # NOTE Split the previous segment for transition
 
               if trim_prev_at > 0
-                filters.concat(
+                @filters.concat(
                   Filter.split "#{lbl_pad}:v", ["#{lbl_pad}a:v", "#{lbl_pad}b:v"]
                 )  if channel?(:video)
-                filters.concat(
+                @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"
@@ -99,10 +115,10 @@ module Ffmprb
 
               new_prev_lbl = "tm#{prev_lbl}#{i}a"
 
-              filters.concat(
+              @filters.concat(
                 Filter.trim 0, trim_prev_at, "#{lbl_pad}:v", "#{new_prev_lbl}:v"
               )  if channel?(:video)
-              filters.concat(
+              @filters.concat(
                 Filter.atrim 0, trim_prev_at, "#{lbl_pad}:a", "#{new_prev_lbl}:a"
               )  if channel?(:audio)
 
@@ -114,27 +130,34 @@ module Ffmprb
 
               # NOTE snip the end of the previous segment and combine with this reel
 
-              lbl_end1 = "tm#{i}b"
-              lbl_reel = "tn#{i}"
+              lbl_end1 = "o#{@idx}tm#{i}b"
+              lbl_reel = "o#{@idx}tn#{i}"
+
               if !lbl  # no reel
-                lbl_aux = "bk#{i}"
-                filters.concat(
-                  Filter.blank_source curr_reel.transition_length, target_resolution, channel(:video).fps, "#{lbl_aux}:v"
+                lbl_aux = "o#{@idx}bk#{i}"
+                @filters.concat(
+                  Filter.blank_source transition_length, channel(:video).resolution, channel(:video).fps, "#{lbl_aux}:v"
                 )  if channel?(:video)
-                filters.concat(
-                  Filter.silent_source curr_reel.transition_length, "#{lbl_aux}:a"
+                @filters.concat(
+                  Filter.silent_source transition_length, "#{lbl_aux}:a"
                 )  if channel?(:audio)
               end  # NOTE else hope lbl is long enough for the transition
-              filters.concat(
-                Filter.trim trim_prev_at, trim_prev_at + curr_reel.transition_length, "#{lbl_pad_}:v", "#{lbl_end1}:v"
+
+              @filters.concat(
+                Filter.trim trim_prev_at, trim_prev_at + 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"
+              @filters.concat(
+                Filter.atrim trim_prev_at, trim_prev_at + 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)
-              )
+
+              # TODO the only supported transition, see #*lay
+              @filters.concat(
+                Filter.blend_v transition_length, channel(:video).resolution, channel(:video).fps, ["#{lbl_end1}:v", "#{lbl || lbl_aux}:v"], "#{lbl_reel}:v"
+              ) if channel?(:video)
+              @filters.concat(
+                Filter.blend_a transition_length, ["#{lbl_end1}:a", "#{lbl || lbl_aux}:a"], "#{lbl_reel}:a"
+              ) if channel?(:audio)
+
               lbl = lbl_reel
             end
 
@@ -145,12 +168,12 @@ module Ffmprb
 
         segments.compact!
 
-        lbl_out = 'oo'
+        lbl_out = "o#{@idx}o"
 
-        filters.concat(
+        @filters.concat(
           Filter.concat_v segments.map{|s| "#{s}:v"}, "#{lbl_out}:v"
         )  if channel?(:video)
-        filters.concat(
+        @filters.concat(
           Filter.concat_a segments.map{|s| "#{s}:a"}, "#{lbl_out}:a"
         )  if channel?(:audio)
 
@@ -159,22 +182,22 @@ module Ffmprb
         # 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
+          next  if over_reel.duck  # NOTE this is currently a single case of multi-process... process
 
           fail Error, "Video overlays are not implemented just yet, sorry..."  if over_reel.reel.channel?(:video)
 
           # Audio overlaying
 
-          lbl_nxt = "oo#{i}"
+          lbl_nxt = "o#{@idx}o#{i}"
 
-          lbl_over = "ol#{i}"
-          filters.concat(  # NOTE audio only, see above
-            over_reel.reel.filters_for lbl_over, process: process, output: self
+          lbl_over = "o#{@idx}l#{i}"
+          @filters.concat(  # NOTE audio only, see above
+            over_reel.reel.filters_for lbl_over, video: false, audio: channel(:audio)
           )
-          filters.concat(
+          @filters.concat(
             Filter.copy "#{lbl_out}:v", "#{lbl_nxt}:v"
           )  if channel?(:video)
-          filters.concat(
+          @filters.concat(
             Filter.amix_to_first_same_volume ["#{lbl_out}:a", "#{lbl_over}:a"], "#{lbl_nxt}:a"
           )  if channel?(:audio)
 
@@ -183,67 +206,77 @@ module Ffmprb
 
         # NOTE multi-process overlays last
 
-        channel_lbl_ios = {}  # XXX this is a spaghetti machine
-        channel_lbl_ios["#{lbl_out}:v"] = @io  if channel?(:video)
-        channel_lbl_ios["#{lbl_out}:a"] = @io  if channel?(:audio)
+        @channel_lbl_ios = {}  # XXX this is a spaghetti machine
+        @channel_lbl_ios["#{lbl_out}:v"] = @io  if channel?(:video)
+        @channel_lbl_ios["#{lbl_out}:a"] = @io  if channel?(:audio)
 
-        # XXX supporting just "full" overlays for now, see exception in #add_reel
+        # TODO supporting just "full" overlays for now, see exception in #add_reel
         @overlays.to_a.each_with_index do |over_reel, i|
 
-          # XXX this is currently a single case of multi-process... process
+          # NOTE this is currently a single case of multi-process... process
           if over_reel.duck
             fail Error, "Don't know how to duck video... yet"  if over_reel.duck != :audio
 
             # So ducking just audio here, ye?
+            # XXX check if we're on audio channel
 
-            main_a_o = channel_lbl_ios["#{lbl_out}:a"]
-            fail Error, "Main output does not contain audio to duck"  unless main_a_o
+            main_av_o = @channel_lbl_ios["#{lbl_out}:a"]
+            fail Error, "Main output does not contain audio to duck"  unless main_av_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|
-              channel_lbl_ios[channel_lbl] = main_a_inter_o  if io == main_a_o  # XXX ~~~spaghetti
+            # NOTE what really must be done here (optimisation & compatibility):
+            # - output v&a through non-compressed pipes
+            # - v-output will be input to the new v+a merging+encoding process
+            # - a-output will go through the ducking process below and its output will be input to the m+e process above
+            # - v-output will have to use another thread-buffered pipe
+            main_av_inter_o = File.temp_fifo(main_av_o.extname)
+            @channel_lbl_ios.each do |channel_lbl, io|
+              @channel_lbl_ios[channel_lbl] = main_av_inter_o  if io == main_av_o  # XXX ~~~spaghetti
             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"
+            Ffmprb.logger.debug "Re-routed the main audio output (#{main_av_inter_o.path}->...->#{main_av_o.path}) through the process of audio ducking"
 
-            overlay_i, overlay_o = File.threaded_buffered_fifo(Process.intermediate_channel_extname :audio)
-            lbl_over = "ol#{i}"
-            filters.concat(
-              over_reel.reel.filters_for lbl_over, process: process, output: self, video: false, audio: true
+            over_a_i, over_a_o = File.threaded_buffered_fifo(Process.intermediate_channel_extname :audio)
+            lbl_over = "o#{@idx}l#{i}"
+            @filters.concat(
+              over_reel.reel.filters_for lbl_over, video: false, audio: channel(:audio)
             )
-            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"
+            @channel_lbl_ios["#{lbl_over}:a"] = over_a_i
+            Ffmprb.logger.debug "Routed and buffering an auxiliary output fifos (#{over_a_i.path}>#{over_a_o.path}) for overlay"
 
-            inter_i, inter_o = File.threaded_buffered_fifo(main_a_inter_o.extname)
+            inter_i, inter_o = File.threaded_buffered_fifo(main_av_inter_o.extname)
             Ffmprb.logger.debug "Allocated fifos to buffer media (#{inter_i.path}>#{inter_o.path}) while finding silence"
 
             Util::Thread.new "audio ducking" do
-              silence = Ffmprb.find_silence(main_a_inter_o, inter_i)
+              silence = Ffmprb.find_silence(main_av_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_o, overlay_o, silence, main_a_o,
-                video: (channel?(:video)? {resolution: target_resolution, fps: target_fps}: false)
+              Process.duck_audio inter_o, over_a_o, silence, main_av_o, video: channel(:video), audio: channel(:audio)
             end
           end
 
         end
 
-        Filter.complex_options(filters).tap do |options|
+        @filters
+      end
 
-          io_channel_lbls = {}  # XXX ~~~spaghetti
-          channel_lbl_ios.each do |channel_lbl, io|
-            (io_channel_lbls[io] ||= []) << channel_lbl
-          end
-          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_lbls.size > 1 && channel_lbl =~ /:a$/
-            end
-            options << io.path
-          end
+      def options
+        fail Error, "Must generate filters first."  unless @channel_lbl_ios
 
+        options = []
+
+        io_channel_lbls = {}  # XXX ~~~spaghetti
+        @channel_lbl_ios.each do |channel_lbl, io|
+          (io_channel_lbls[io] ||= []) << channel_lbl
+        end
+        io_channel_lbls.each do |io, channel_lbls|
+          channel_lbls.each do |channel_lbl|
+            options << '-map' << "[#{channel_lbl}]"
+          end
+          options.concat self.class.audio_cmd_options(channel :audio)  if channel? :audio
+          options << io.path
         end
+
+        options
       end
 
       def roll(
@@ -263,29 +296,24 @@ module Ffmprb
       def overlay(
         reel,
         at: 0,
-        transition: nil,
         duck: nil
       )
         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)
+        add_snip reel, at, duck
       end
 
-      def channel?(medium)
-        @channels.include?(medium) && @io.channel?(medium) && reels_channel?(medium)
+      def channel(medium)
+        @channels[medium]
       end
 
-      def channel?(medium, force=false)
-        return !!@channels && @channels.include?(medium) && @io.channel?(medium)  if force
-
-        (!@channels || @channels.include?(medium)) && @io.channel?(medium) &&
-          reels_channel?(medium)
+      def channel?(medium)
+        !!channel(medium)
       end
 
-      # XXX TMP protected
+      protected
 
       def resolve(io)
         return io  unless io.is_a? String
@@ -300,7 +328,7 @@ module Ffmprb
         end
       end
 
-      # XXX TMP private
+      private
 
       def reels_channel?(medium)
         @reels.to_a.all?{|r| !r.reel || r.reel.channel?(medium)}
@@ -310,29 +338,22 @@ module Ffmprb
         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
+        # NOTE limited functionality: transition = {effect => duration}
+        # TODO temporary obviously, see rendering
+        trans =
+          if transition
+            fail "Unsupported (yet) transition, sorry."  unless
+              transition.size == 1 && transition[:blend]
+            OpenStruct.new length: transition[:blend].to_f
+          end
 
         (@reels ||= []) <<
-          OpenStruct.new(reel: reel, after: after, transition: transition, transition_length: transition_length, full_screen?: full_screen)
+          OpenStruct.new(reel: reel, after: after, transition: trans, full_screen?: full_screen)
       end
 
-      def target_width
-        @target_width ||= @resolution.to_s.split('x')[0].to_i.tap do |width|
-          raise Error, "Width (#{width}) must be divisible by 2, sorry"  unless width % 2 == 0
-        end
-      end
-      def target_height
-        @target_height ||= @resolution.to_s.split('x')[1].to_i.tap do |height|
-          raise Error, "Height (#{height}) must be divisible by 2, sorry"  unless height % 2 == 0
-        end
-      end
-      def target_resolution
-        "#{target_width}x#{target_height}"
-      end
-
-      def target_fps
-        @fps
+      def add_snip(reel, at, duck)
+        (@overlays ||= []) <<
+          OpenStruct.new(reel: reel, at: at, duck: duck)
       end
 
     end

data/lib/ffmprb/process.rb

@@ -9,6 +9,10 @@ module Ffmprb
       attr_accessor :duck_audio_transition_length,
         :duck_audio_transition_in_start, :duck_audio_transition_out_start
 
+      attr_accessor :output_video_resolution
+      attr_accessor :output_video_fps
+      attr_accessor :output_audio_encoder
+
       attr_accessor :timeout
 
       def intermediate_channel_extname(*media)
@@ -23,20 +27,35 @@ module Ffmprb
         end
       end
 
+      def output_video_options
+        {
+          resolution: output_video_resolution,
+          fps: output_video_fps
+        }
+      end
+      def output_audio_options
+        {
+          encoder: output_audio_encoder
+        }
+      end
+
+      # NOTE Temporarily, av_main_i/o and not a_main_i/o
       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,
+        volume_lo: duck_audio_volume_lo,
+        volume_hi: duck_audio_volume_hi,
         silent_min: duck_audio_silent_min,
-        video: {resolution: Ffmprb::CGA, fps: 30}  # XXX temporary
+        video:,  # NOTE Temporarily, video should not be here
+        audio:
         )
-        Ffmprb.process(av_main_i, a_overlay_i, silence, av_main_o) do |main_input, overlay_input, duck_data, main_output|
+        Ffmprb.process do
 
-          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
+          in_main = input(av_main_i)
+          in_over = input(a_overlay_i)
+          output(av_main_o, video: video, audio: audio) do
             roll in_main
 
             ducked_overlay_volume = {0.0 => volume_lo}
-            duck_data.each do |silent|
+            silence.each do |silent|
               next  if silent.end_at && silent.start_at && (silent.end_at - silent.start_at) < silent_min
 
               transition_in_start = silent.start_at + Process.duck_audio_transition_in_start
@@ -63,57 +82,79 @@ module Ffmprb
 
     attr_reader :timeout
 
-    def initialize(*args, **opts, &blk)
-      @inputs = []
-      @timeout = opts[:timeout] || self.class.timeout
+    def initialize(*args, **opts)
+      @inputs, @outputs = [], []
+      @timeout = opts.delete(:timeout) || self.class.timeout
+
+      @ignore_broken_pipe = opts.delete(:ignore_broken_pipe)  # XXX SPEC ME
+      fail Error, "Unknown options: #{opts}"  unless opts.empty?
     end
 
-    def input(io, only: nil)
-      Input.new(io, only: only).tap do |inp|
+    def input(io)
+      Input.new(io, self).tap do |inp|
         @inputs << inp
       end
     end
 
-    def output(io, only: nil, resolution: Ffmprb::CGA, fps: 30, &blk)
-      fail Error, "Just one output for now, sorry."  if @output
+    def temp_input(extname)  # XXX SPEC ME
+      input(nil).tap do |inp|
+        inp.temporise! extname
+      end
+    end
+
+    def input_label(input)
+      @inputs.index input
+    end
 
-      @output = Output.new(io, only: only, resolution: resolution, fps: fps).tap do |out|
-        out.instance_exec &blk
+    def output(io, video: true, audio: true, &blk)
+      Output.new(io, @outputs.size,
+        video: channel_params(video, self.class.output_video_options),
+        audio: channel_params(audio, self.class.output_audio_options)
+      ).tap do |out|
+        @outputs << out
+        out.instance_exec &blk  if blk
       end
     end
 
     # NOTE the one and the only entry-point processing function which spawns threads etc
-    def run(limit: nil)  # (async: false)
+    def run(limit: nil)  # TODO (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
+        # XXX just to return something -- no apparent practical use
+        cmd = command
+        Util.ffmpeg(*cmd, limit: limit, timeout: timeout, ignore_broken_pipe: @ignore_broken_pipe).tap do |res|
           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)
-      case obj
-      when Input
-        @inputs.find_index(obj)
-      end
-    end
-
     private
 
     def command
-      input_options + output_options
+      input_options + filter_options + output_options
     end
 
     def input_options
       @inputs.map(&:options).flatten(1)
     end
 
+    def filter_options
+      Filter.complex_options @outputs.map(&:filters).reduce(:+)
+    end
+
     def output_options
-      @output.options_for self
+      @outputs.map(&:options).flatten(1)
+    end
+
+    def channel_params(value, default)
+      if value
+        default.merge(value == true ? {} : value.to_h)
+      elsif value != false
+        {}
+      end
     end
 
   end

data/lib/ffmprb/util/synchro.rb

@@ -1,4 +1,4 @@
-# XXX unused and commented out
+# TODO unused and commented out
 # module Ffmprb
 #
 #   module Util

data/lib/ffmprb/util/thread.rb

@@ -5,7 +5,7 @@ module Ffmprb
     # NOTE doesn't have specs (and not too proud about it)
     class Thread < ::Thread
 
-      class Error < StandardError; end
+      class Error < Ffmprb::Error; end
       class ParentError < Error; end
 
       class << self
@@ -70,7 +70,7 @@ module Ffmprb
         sync_q.deq
       end
 
-      # XXX protected: none of these methods should be called by a user code, the only public methods are above
+      # TODO 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?