aspera-cli 4.25.6 → 4.26.1

data/lib/aspera/command_line_builder.rb

@@ -2,6 +2,7 @@
 
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/schema/registry'
 require 'yaml'
 module Aspera
   # Helper class to build command line from a parameter list (key-value hash)
@@ -35,9 +36,9 @@ module Aspera
 
     class << self
       # Called by provider of definition before constructor of this class so that schema has all mandatory fields
-      def read_schema(folder, name, ascp: false)
-        schema = YAML.load_file(File.join(folder, "#{name}.schema.yaml"))
-        validate_schema(schema, ascp: ascp)
+      # @return [Aspera::Schema::Reader]
+      def read_schema(name_sym, ascp: false)
+        validate_schema(Schema::Registry.instance.reader(name_sym), ascp: ascp)
       end
 
       # @param agent      [Symbol] Transfer agent name
@@ -49,29 +50,32 @@ module Aspera
 
       private
 
+      DIRECT_PROPERTIES = %w[x-cli-option x-cli-envvar x-cli-special].freeze
+
       # Fill default values for some fields in the schema
-      # @param schema [Hash]    The JSON schema
-      # @param ascp   [Boolean] `true` if ascp
+      # @param schema [Schema::Reader] The JSON schema
+      # @param ascp [Boolean] `true` if `ascp`
+      # @return [Schema::Reader] The JSON schema
       def validate_schema(schema, ascp: false)
-        direct_props = %w[x-cli-option x-cli-envvar x-cli-special].freeze
-        schema['properties'].each do |name, info|
-          Aspera.assert_type(info, Hash){"#{info.class} for #{name}"}
-          unsupported_keys = info.keys - PROPERTY_KEYS
+        Aspera.assert_type(schema, Schema::Reader){'schema'}
+        Aspera.assert(schema.current.key?('properties')){"Schema must have 'properties': #{schema}"}
+        schema.each_property do |property_schema, name, _full_name|
+          node = property_schema.current
+          unsupported_keys = node.keys - PROPERTY_KEYS
           Aspera.assert(unsupported_keys.empty?){"Unsupported definition keys: #{unsupported_keys}"}
-          Aspera.assert(info.key?('type') || info.key?('enum')){"Missing type for #{name} in #{schema['description']}"}
-          Aspera.assert(info['type'].eql?('boolean')){"switch must be bool: #{name}"} if info['x-cli-switch'] && !info['x-cli-special']
-          info['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if info['x-cli-option'].eql?(true) || (info['x-cli-switch'].eql?(true) && !info.key?('x-cli-option'))
-          Aspera.assert(direct_props.any?{ |i| info.key?(i)}, type: :warn){name} if ascp && supported_by_agent(:direct, info)
-          info.freeze
-          validate_schema(info, ascp: ascp) if info['type'].eql?('object') && info['properties']
-          validate_schema(info['items'], ascp: ascp) if info['type'].eql?('array') && info['items'] && info['items']['properties']
+          Aspera.assert(node.key?('type') || node.key?('enum')){"Missing type for #{name} in #{schema.current.dig('description').current}"}
+          Aspera.assert(node['type'].eql?('boolean')){"switch must be bool: #{name}"} if node['x-cli-switch'] && !node['x-cli-special']
+          node['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if node['x-cli-option'].eql?(true) || (node['x-cli-switch'].eql?(true) && !node.key?('x-cli-option'))
+          Aspera.assert(DIRECT_PROPERTIES.any?{ |i| node.key?(i)}, type: :warn){name} if ascp && supported_by_agent(:direct, node)
+          node.freeze
         end
         schema
       end
     end
 
-    # @param [Hash] object with parameters
-    # @param [Hash] schema JSON schema
+    # @param object [Hash] object with parameters
+    # @param schema [Schema::Reader] JSON schema
+    # @param convert [Object] function to convert value
     def initialize(object, schema, convert)
       @object = object # keep reference so that it can be modified by caller before calling `process_params`
       @schema = schema

data/lib/aspera/dot_container.rb

@@ -61,6 +61,7 @@ module Aspera
     def to_dotted
       result = {}
       until @stack.empty?
+        # path: Array, current: Array or Hash or other
         path, current = @stack.pop
         to_insert = nil
         # empty things are left intact
@@ -78,8 +79,11 @@ module Aspera
             elsif current.all?{ |i| i.is_a?(Hash) && i.keys == ['name']}
               to_insert = current.map{ |i| i['name']}
             # Array of Hashes with only 'name' and 'value' keys -> Hash of key/values
-            elsif current.all?{ |i| i.is_a?(Hash) && i.keys.sort == %w[name value]}
-              add_elements(path, current.to_h{ |i| [i['name'], i['value']]})
+            elsif current.all?{ |i| i.is_a?(Hash) && i.key?('name') && i.key?('value') && i.length <= 3}
+              # if there is an extra key, other than 'name' and 'value', insert that key as is
+              add_elements(path, current.flat_map{ |h| h.except('name', 'value').to_a})
+              # Insert name/value pairs as Hash
+              add_elements(path, current.to_h{ |h| h.values_at('name', 'value')})
             else
               add_elements(path, current.each_with_index.map{ |v, i| [i, v]})
             end
@@ -97,7 +101,7 @@ module Aspera
     # Add elements of enumerator to the @stack, in reverse order
     def add_elements(path, enum)
       enum.reverse_each do |key, value|
-        @stack.push([path + [key], value])
+        @stack.push([path + [key.to_s], value])
       end
       nil
     end

data/lib/aspera/environment.rb

@@ -91,9 +91,9 @@ module Aspera
       #
       # @param cmd [Array<#to_s>] The executable and its arguments.
       # @param mode [:execute, :background, :capture] The execution strategy:
-      #   - `:execute`    Uses {Kernel.system}. Returns `true`, `false`, or `nil`.
+      #   - `:execute`    Uses {Kernel.system}. Returns `true`, `false`, or `nil`. (Default)
       #   - `:background` Uses {Process.spawn}. Returns the spawned process PID.
-      #   - `:capture`    Uses {Open3.capture3}. Returns captured output and status.
+      #   - `:capture`    Uses {Open3.capture3}. Returns captured out, err, and status.
       #
       # @param kwargs [Hash] Additional options forwarded to the underlying call.
       #
@@ -151,7 +151,7 @@ module Aspera
       # @param path [String] the file path
       # @param force [Boolean] if true, overwrite the file
       # @param mode [Integer] the file mode (permissions)
-      # @block [Proc] return the content to write to the file
+      # @yieldreturn [String] The content to write to the file
       def write_file_restricted(path, force: false, mode: nil)
         Aspera.assert(block_given?, type: Aspera::InternalError)
         if force || !File.exist?(path)
@@ -280,7 +280,7 @@ module Aspera
       when Environment::OS_MACOS then return self.class.secure_execute('open', uri.to_s)
       when Environment::OS_WINDOWS then return self.class.secure_execute('start', 'explorer', %Q{"#{uri}"})
       when Environment::OS_LINUX   then return self.class.secure_execute('xdg-open', uri.to_s)
-      else Assert.error_unexpected_value(os){'no graphical open method'}
+      else Aspera.error_unexpected_value(os){'no graphical open method'}
       end
     end
 
@@ -316,6 +316,7 @@ module Aspera
 
     # Replacement character for illegal filename characters
     # Can also be used as safe "join" character
+    # @return [String] One character
     def safe_filename_character
       return REPLACE_CHARACTER if @file_illegal_characters.nil? || @file_illegal_characters.empty?
       @file_illegal_characters[0]
@@ -333,7 +334,7 @@ module Aspera
       filename = filename.chop while filename.end_with?(' ', '.')
       if @file_illegal_characters&.size.to_i >= 2
         # replace all illegal characters with safe_char
-        filename = filename.tr(@file_illegal_characters[1..-1], safe_char)
+        filename = filename.tr(@file_illegal_characters[1..], safe_char)
       end
       # ensure only one safe_char is used at a time
       return filename.gsub(/#{Regexp.escape(safe_char)}+/, safe_char).chomp(safe_char)

data/lib/aspera/formatter_interface.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'aspera/assert'
+
+module Aspera
+  # Common interface for documentation formatters
+  # Used by Schema::Documentation to format tables
+  module FormatterInterface
+    Aspera.require_method!(:tick)
+    Aspera.require_method!(:special_format)
+    Aspera.require_method!(:check_row)
+    Aspera.require_method!(:markdown_text)
+  end
+end

data/lib/aspera/hash_ext.rb

@@ -9,6 +9,12 @@ class ::Hash
     merge!(second){ |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge!(v2) : v2}
   end
 
+  # Recursively iterate through hash and execute block on leaf values
+  # @param memory [Object, nil] Optional memory object passed to block
+  # @yieldparam hash [Hash] The current hash
+  # @yieldparam key [Object] The current key
+  # @yieldparam value [Object] The current value (non-Hash)
+  # @yieldparam memory [Object, nil] The memory object
   def deep_do(memory = nil, &block)
     each do |key, value|
       if value.is_a?(Hash)

data/lib/aspera/log.rb

@@ -77,7 +77,7 @@ module Aspera
       # @param name   [String, Symbol]  Name of object dumped
       # @param object [Hash, nil]       Data to dump
       # @param level  [Symbol]          Debug level
-      # @param block  [Proc, nil]       Give computed object
+      # @yieldreturn [Object] Computed object to dump (alternative to object parameter)
       def dump(name, object = nil, level: :debug, &block)
         return unless instance.logger.send(:"#{level}?")
         Aspera.assert(object.nil? || block.nil?){'Use either object, or block, not both'}
@@ -93,12 +93,13 @@ module Aspera
             JSON.pretty_generate(object) rescue PP.pp(object, +'')
           when :ruby
             PP.pp(object, +'')
-          else error_unexpected_value(instance.dump_format){'dump format'}
+          else Aspera.error_unexpected_value(instance.dump_format){'dump format'}
           end
-        "#{name.to_s.green} (#{instance.dump_format})=\n#{dump_text}"
+        "#{name.to_s.green}(#{instance.dump_format})#{object.class}=\n#{dump_text}"
       end
 
       # Capture the output of $stderr and log it at debug level
+      # @yieldreturn [void] Code block whose stderr output will be captured
       def capture_stderr
         real_stderr = $stderr
         $stderr = StringIO.new
@@ -192,7 +193,7 @@ module Aspera
         end
         # Use `local2` facility, like other Aspera components
         @logger = Syslog::Logger.new(@program_name, Syslog::LOG_LOCAL2)
-      else error_unexpected_value(new_log_type){"log type (#{LOG_TYPES.join(', ')})"}
+      else Aspera.error_unexpected_value(new_log_type){"log type (#{LOG_TYPES.join(', ')})"}
       end
       @logger.level = current_severity_integer
       @logger_type = new_log_type

data/lib/aspera/markdown.rb

@@ -8,11 +8,14 @@ module Aspera
     HTML_BREAK = '<br/>'
 
     class << self
+      COL_WIDTH = 80
       # Generate markdown from the provided 2D table
+      # @param table [Array<Array<String>>] 2D array of strings
+      # @return [String] markdown table
       def table(table)
         # get max width of each columns
         col_widths = table.transpose.map do |col|
-          [col.flat_map{ |c| c.to_s.delete('`').split(HTML_BREAK).map(&:size)}.max, 80].min
+          [col.flat_map{ |c| c.to_s.delete('`').split(HTML_BREAK).map(&:size)}.max, COL_WIDTH].min
         end
         headings = table.shift
         table.unshift(col_widths.map{ |col_width| '-' * col_width})

data/lib/aspera/oauth/factory.rb

@@ -33,7 +33,7 @@ module Aspera
         # Extract only token from Authorization (remove scheme)
         def bearer_token(authorization)
           Aspera.assert(bearer_auth?(authorization)){'not a bearer token, wrong prefix scheme'}
-          return authorization[SPACE_BEARER_AUTH_SCHEME.length..-1]
+          return authorization.delete_prefix(SPACE_BEARER_AUTH_SCHEME)
         end
 
         # Generate a unique cache id for a token creator

data/lib/aspera/preview/file_types.rb

@@ -14,7 +14,7 @@ module Aspera
       # values for conversion_type : input format
       CONVERSION_TYPES = %i[image office pdf plaintext video].freeze
 
-      # special cases for mime types
+      # Special cases for MIME types
       # spellchecker:disable
       SUPPORTED_MIME_TYPES = {
         'application/json'                   => :plaintext,

data/lib/aspera/preview/generator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # ffmpeg options:
-# spellchecker:ignore pauseframes libx264 trunc bufsize muxer apng libmp3lame maxrate posterize movflags faststart
+# spellchecker:ignore soffice pauseframes libx264 trunc bufsize muxer apng libmp3lame maxrate posterize movflags faststart
 # spellchecker:ignore palettegen paletteuse pointsize bordercolor repage lanczos unoconv optipng reencode conv transframes
 
 require 'aspera/preview/options'
@@ -12,37 +12,41 @@ require 'aspera/assert'
 
 module Aspera
   module Preview
-    # generate one preview file for one format for one file at a time
+    # Generates one preview file for one format for one file at a time.
     class Generator
-      # values for preview_format : output format
+      # Values for preview_format: output format.
       PREVIEW_FORMATS = %i[png mp4].freeze
 
+      # List of valid ffmpeg option keys for reencode configuration.
       FFMPEG_OPTIONS_LIST = %w[in out].freeze
 
-      # CLI needs to know conversion type to know if need skip it
-      # one of CONVERSION_TYPES
-      attr_reader :conversion_type
+      # CLI needs to know conversion type to know if need skip it.
+      # One of CONVERSION_TYPES.
+      attr_reader :conversion_type, :destination
 
-      # Node API MIME types are from: http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
+      # Node API MIME types are from: http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types.
       # The resulting preview file type is taken from destination file extension.
-      # Conversion methods are provided by private methods: convert_<conversion_type>_to_<preview_format>
-      #   -> conversion_type is one of FileTypes::CONVERSION_TYPES
-      #   -> preview_format is one of Generator::PREVIEW_FORMATS
-      # The conversion video->mp4 is implemented in methods: convert_video_to_mp4_using_<video_conversion>
-      #  -> conversion method is one of Generator::VIDEO_CONVERSION_METHODS
-      # @param src           [String]  source file path
-      # @param dst           [String]  destination file path
-      # @param options       [Options] All conversion options
-      # @param main_temp_dir [String]  Main temp folder, sub folder will be created for generation
-      # @param api_mime_type [String,nil] Optional MIME type as provided by node api (or nil)
-      def initialize(src, dst, options, main_temp_dir, api_mime_type)
-        @source_file_path = src
-        @destination_file_path = dst
+      # Conversion methods are provided by private methods: convert_<conversion_type>_to_<preview_format>.
+      #   -> conversion_type is one of FileTypes::CONVERSION_TYPES.
+      #   -> preview_format is one of Generator::PREVIEW_FORMATS.
+      # The conversion video->mp4 is implemented in methods: convert_video_to_mp4_using_<video_conversion>.
+      #  -> conversion method is one of Generator::VIDEO_CONVERSION_METHODS.
+      # @param src [String] Source file path.
+      # @param dst [String] Destination file path.
+      # @param options [Options] All conversion options.
+      # @param main_temp_dir [String] Main temp folder, sub folder will be created for generation.
+      # @param mime [String, nil] Optional MIME type as provided by node api (or nil).
+      def initialize(src, dst, options, main_temp_dir, mime: nil)
+        # Source file path
+        @source = src
+        # Destination file path
+        @destination = dst
         @options = options
-        @temp_folder = File.join(main_temp_dir, @source_file_path.split('/').last.gsub(/\s/, '_').gsub(/\W/, ''))
-        # extract preview format from extension of target file
-        @preview_format_sym = File.extname(@destination_file_path).gsub(/^\./, '').to_sym
-        conversion_type = FileTypes.instance.conversion_type(@source_file_path, api_mime_type)
+        # temp folder name based on source file
+        @temp_folder = File.join(main_temp_dir, @source.split('/').last.gsub(/\s/, '_').gsub(/\W/, ''))
+        # Extract preview format from extension of target file.
+        @preview_format_sym = File.extname(@destination).gsub(/^\./, '').to_sym
+        conversion_type = FileTypes.instance.conversion_type(@source, mime)
         @processing_method = "convert_#{conversion_type}_to_#{@preview_format_sym}"
         if conversion_type.eql?(:video)
           case @preview_format_sym
@@ -55,82 +59,97 @@ module Aspera
         @processing_method = @processing_method.to_sym
         Log.log.debug{"method: #{@processing_method}"}
         Aspera.assert(respond_to?(@processing_method, true)){"no processing known for #{conversion_type} -> #{@preview_format_sym}"}
+        command = [:magick] + %w[identify -list font]
+        magick_fonts = Utils.parse_magick_fonts(Utils.execute(*command, mode: :capture).first)
+        Aspera.assert(magick_fonts[:fonts].any?{ |f| f[:name].eql?(@options.thumb_text_font)}){"Missing font #{@options.thumb_text_font} in #{command}"}
       end
 
-      # Create preview as specified in constructor.
+      # Creates preview as specified in constructor.
       def generate
-        Log.log.debug{"#{@source_file_path}->#{@destination_file_path} (#{@processing_method})"}
+        Log.log.debug{"#{@source}->#{@destination} (#{@processing_method})"}
         begin
           send(@processing_method)
-          # check that generated size does not exceed maximum
-          result_size = File.size(@destination_file_path)
+          # Check that generated size does not exceed maximum.
+          result_size = File.size(@destination)
           Log.log.warn{"preview size exceeds maximum allowed #{result_size} > #{@options.max_size}"} if result_size > @options.max_size
-        rescue StandardError => e
-          Log.log.error{"Ignoring: #{e.class} #{e.message}"}
-          Log.log.debug(e.backtrace.join("\n").red)
-          FileUtils.cp(File.expand_path(@preview_format_sym.eql?(:mp4) ? 'video_error.png' : 'image_error.png', File.dirname(__FILE__)), @destination_file_path)
         ensure
           FileUtils.rm_rf(@temp_folder)
         end
       end
 
+      # Path to error image corresponding to preview type.
+      # @return [String] The path to the error image.
+      def error_asset
+        File.expand_path(@preview_format_sym.eql?(:mp4) ? 'video_error.png' : 'image_error.png', File.dirname(__FILE__))
+      end
+
       private
 
       # Creates a unique temp folder for file.
+      # @return [String] The temporary folder path.
       def this_tmpdir
         FileUtils.mkdir_p(@temp_folder)
         return @temp_folder
       end
 
-      # @param duration of video
-      # @param start_offset of parts
-      # @param total_count of parts
-      # @param index of part (start at 1)
-      # @return [Integer] offset in seconds suitable for ffmpeg -ss option
+      # Calculates offset in seconds for video frame extraction.
+      # @param duration [Float] Duration of video in seconds.
+      # @param start_offset [Numeric] Start offset of parts in seconds.
+      # @param total_count [Integer] Total count of parts.
+      # @param index [Integer] Index of part (starts at 1).
+      # @return [Float] Offset in seconds suitable for ffmpeg -ss option.
       def get_offset(duration, start_offset, total_count, index)
         Aspera.assert_type(duration, Float){'duration'}
         return start_offset + ((index - 1) * (duration - start_offset) / total_count)
       end
 
+      # Converts video to MP4 using blend method.
+      # Extracts key frames and blends them with transitions.
       def convert_video_to_mp4_using_blend
-        p_duration = Utils.video_get_duration(@source_file_path)
+        p_duration = Utils.video_get_duration(@source)
         p_start_offset = @options.video_start_sec.to_i
         p_key_frame_count = @options.blend_keyframes.to_i
         last_keyframe = nil
         current_index = 1
+        frame_rate_hz = 30
         1.upto(p_key_frame_count) do |i|
-          offset_seconds = get_offset(p_duration, p_start_offset, p_key_frame_count, i)
-          Utils.video_dump_frame(@source_file_path, offset_seconds, @options.video_scale, this_tmpdir, current_index)
+          Utils.video_dump_frame(
+            @source,
+            get_offset(p_duration, p_start_offset, p_key_frame_count, i),
+            @options.video_scale,
+            Utils.get_tmp_num_filepath(this_tmpdir, current_index)
+          )
           Utils.video_dupe_frame(this_tmpdir, current_index, @options.blend_pauseframes)
           Utils.video_blend_frames(this_tmpdir, last_keyframe, current_index) unless last_keyframe.nil?
-          # go to last dupe frame
+          # Go to last dupe frame.
           last_keyframe = current_index + @options.blend_pauseframes
-          # go after last dupe frame and keep space to blend
+          # Go after last dupe frame and keep space to blend.
           current_index = last_keyframe + 1 + @options.blend_transframes
         end
         Utils.ffmpeg(
           in_f: Utils.ffmpeg_fmt(this_tmpdir),
           in_p: ['-framerate', @options.blend_fps],
-          out_f: @destination_file_path,
+          out_f: @destination,
           out_p: [
             '-filter:v', "scale='trunc(iw/2)*2:trunc(ih/2)*2'",
             '-codec:v', 'libx264',
-            '-r', 30,
+            '-r', frame_rate_hz,
             '-pix_fmt', 'yuv420p'
           ]
         )
       end
 
-      # generate n clips starting at offset
+      # Converts video to MP4 using clips method.
+      # Generates n clips starting at offset and concatenates them.
       def convert_video_to_mp4_using_clips
-        p_duration = Utils.video_get_duration(@source_file_path)
+        p_duration = Utils.video_get_duration(@source)
         file_list_file = File.join(this_tmpdir, 'clip_files.txt')
         File.open(file_list_file, 'w+') do |f|
           1.upto(@options.clips_count.to_i) do |i|
             offset_seconds = get_offset(p_duration, @options.video_start_sec.to_i, @options.clips_count.to_i, i)
             tmp_file_name = format('clip%04d.mp4', i)
             Utils.ffmpeg(
-              in_f: @source_file_path,
+              in_f: @source,
               in_p: ['-ss', offset_seconds * 0.9],
               out_f: File.join(this_tmpdir, tmp_file_name),
               out_p: [
@@ -143,17 +162,18 @@ module Aspera
             f.puts("file '#{tmp_file_name}'")
           end
         end
-        # concat clips
+        # Concat clips.
         Utils.ffmpeg(
           in_f: file_list_file,
           in_p: ['-f', 'concat'],
-          out_f: @destination_file_path,
+          out_f: @destination,
           out_p: ['-codec', 'copy']
         )
         File.delete(file_list_file)
       end
 
-      # do a simple re-encoding
+      # Converts video to MP4 using re-encoding method.
+      # Performs a simple re-encoding with configurable ffmpeg options.
       def convert_video_to_mp4_using_reencode
         options = @options.reencode_ffmpeg
         Aspera.assert_type(options, Hash){'reencode_ffmpeg'}
@@ -162,11 +182,11 @@ module Aspera
           Aspera.assert_type(v, Array){k}
         end
         Utils.ffmpeg(
-          in_f: @source_file_path,
+          in_f: @source,
           in_p: options['in'] || ['-ss', @options.video_start_sec.to_i * 0.9],
-          out_f: @destination_file_path,
+          out_f: @destination,
           out_p: options['out'] || [
-            '-t', '60',
+            '-t', 60,
             '-codec:v', 'libx264',
             '-profile:v', 'high',
             '-pix_fmt', 'yuv420p',
@@ -184,89 +204,124 @@ module Aspera
         )
       end
 
+      # Converts video to PNG using fixed frame method.
+      # Generates a static thumbnail at a specific time offset.
       def convert_video_to_png_using_fixed
         Utils.video_dump_frame(
-          @source_file_path,
-          Utils.video_get_duration(@source_file_path) * @options.thumb_vid_fraction,
+          @source,
+          Utils.video_get_duration(@source) * @options.thumb_vid_fraction,
           @options.thumb_vid_scale,
-          @destination_file_path
+          @destination
         )
       end
 
-      # https://trac.ffmpeg.org/wiki/SponsoringPrograms/GSoC/2015#AnimatedPortableNetworkGraphicsAPNG
-      # ffmpeg -h muxer=apng
-      # thumb is 32x32
-      # ffmpeg  output.png
+      # Converts video to animated PNG (APNG).
+      # Creates an animated thumbnail with looping.
+      # @see https://trac.ffmpeg.org/wiki/SponsoringPrograms/GSoC/2015#AnimatedPortableNetworkGraphicsAPNG
       def convert_video_to_png_using_animated
+        p_duration = Utils.video_get_duration(@source)
+        p_start_offset = @options.video_start_sec.to_i
+        p_max_duration = @options.clips_length.to_i
+        # If video is shorter than start offset + duration, adjust to capture from start.
+        if p_duration <= (p_start_offset + p_max_duration)
+          p_start_offset = 0
+          p_max_duration = p_duration
+        end
         Utils.ffmpeg(
-          in_f: @source_file_path,
+          in_f: @source,
           in_p: [
-            '-ss', 10, # seek to input position
-            '-t', 20 # max seconds
+            '-ss', p_start_offset,
+            '-t', p_max_duration
           ],
-          out_f: @destination_file_path,
+          out_f: @destination,
           out_p: [
-            '-vf', 'fps=5,scale=120:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse',
-            '-loop', 0,
-            '-f', 'gif'
+            '-vf', 'fps=5,scale=120:-1:flags=lanczos',
+            '-plays', 0, # Loop forever (0 = infinite loop for APNG).
+            '-f', 'apng'
           ]
         )
       end
 
+      # Converts office document to PNG.
+      # First converts to PDF, then to PNG image.
       def convert_office_to_png
-        tmp_pdf_file = File.join(this_tmpdir, "#{File.basename(@source_file_path, File.extname(@source_file_path))}.pdf")
-        Utils.external_command(:unoconv, [
-          '-f', 'pdf',
-          '-o', tmp_pdf_file,
-          @source_file_path
-        ])
+        tmp_pdf_file = File.join(this_tmpdir, "#{File.basename(@source, File.extname(@source))}.pdf")
+        case @options.office_conversion
+        when :unoconv
+          Utils.silent_execute(
+            :unoconv,
+            '-f', 'pdf',
+            '-o', tmp_pdf_file,
+            @source
+          )
+        when :soffice
+          Utils.silent_execute(
+            :soffice,
+            '--headless',
+            '--convert-to', 'pdf',
+            '--outdir', File.dirname(tmp_pdf_file),
+            @source
+          )
+          # soffice creates the file with the source name, so we need to rename it if needed.
+          generated_pdf = File.join(File.dirname(tmp_pdf_file), "#{File.basename(@source, File.extname(@source))}.pdf")
+          FileUtils.mv(generated_pdf, tmp_pdf_file) if generated_pdf != tmp_pdf_file
+        else Aspera.error_unexpected_value(@options.office_conversion){'office_conversion'}
+        end
         convert_pdf_to_png(tmp_pdf_file)
       end
 
+      # Converts PDF to PNG image.
+      # @param source_file_path [String, nil] Optional source file path, defaults to @source.
       def convert_pdf_to_png(source_file_path = nil)
-        source_file_path ||= @source_file_path
-        Utils.external_command(:magick, [
+        source_file_path ||= @source
+        Utils.silent_execute(
+          :magick,
           'convert',
           '-size', "x#{@options.thumb_img_size}",
           '-background', 'white',
           '-flatten',
           "#{source_file_path}[0]",
-          @destination_file_path
-        ])
+          @destination
+        )
       end
 
+      # Converts image to PNG thumbnail.
+      # Applies auto-orientation, resizing, and optimization.
       def convert_image_to_png
-        Utils.external_command(:magick, [
+        Utils.silent_execute(
+          :magick,
           'convert',
           '-auto-orient',
           '-thumbnail', "#{@options.thumb_img_size}x#{@options.thumb_img_size}>",
           '-quality', 95,
           '+dither',
           '-posterize', 40,
-          "#{@source_file_path}[0]",
-          @destination_file_path
-        ])
-        Utils.external_command(:optipng, [@destination_file_path])
+          "#{@source}[0]",
+          @destination
+        )
+        Utils.silent_execute(:optipng, @destination)
       end
 
-      # text to png
+      # Converts plain text to PNG image.
+      # Renders first 100 lines of text file as an image.
       def convert_plaintext_to_png
-        # get 100 first lines of text file
-        first_lines = File.foreach(@source_file_path).first(100).join
-        Utils.external_command(:magick, [
+        # Get 100 first lines of text file.
+        first_lines = File.foreach(@source).first(100).join
+        Utils.silent_execute(
+          :magick,
           'convert',
           '-size', "#{@options.thumb_img_size}x#{@options.thumb_img_size}",
-          'xc:white', # define canvas with background color (xc, or canvas) of preceding size
+          'xc:white', # Define canvas with background color (xc, or canvas) of preceding size.
           '-font', @options.thumb_text_font,
           '-pointsize', 12,
-          '-fill', 'black', # font color
+          '-fill', 'black', # Font color.
           '-annotate', '+0+0', first_lines,
-          '-trim', # avoid large blank regions
+          '-trim', # Avoid large blank regions.
           '-bordercolor', 'white',
           '-border', 8,
           '+repage',
-          @destination_file_path
-        ])
+          @destination
+        )
       end
     end
   end