aspera-cli 4.25.6 → 4.26.0

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

data/lib/aspera/preview/options.rb

@@ -10,6 +10,8 @@ module Aspera
       # types of generation for video files
       VIDEO_CONVERSION_METHODS = %i[reencode blend clips].freeze
       VIDEO_THUMBNAIL_METHODS = %i[fixed animated].freeze
+      # methods for office document conversion
+      OFFICE_CONVERSION_METHODS = %i[soffice unoconv].freeze
       # options used in generator
       # for scaling see: https://trac.ffmpeg.org/wiki/Scaling
       # iw/ih : input width or height
@@ -20,11 +22,12 @@ module Aspera
         {name: :thumb_vid_fraction,   default: 0.1,                description: 'png: video: time percent position of snapshot'},
         {name: :thumb_img_size,       default: 800,                description: 'png: non-video: height (and width)'},
         {name: :thumb_text_font,      default: 'Courier',          description: 'png: plaintext: font for text rendering: `magick identify -list font`'},
+        {name: :office_conversion,    default: :soffice,           description: 'office: method for office document conversion', values: OFFICE_CONVERSION_METHODS},
         {name: :video_conversion,     default: :reencode,          description: 'mp4: method for preview generation', values: VIDEO_CONVERSION_METHODS},
         {name: :video_png_conv,       default: :fixed,             description: 'mp4: method for thumbnail generation', values: VIDEO_THUMBNAIL_METHODS},
         {name: :video_scale,          default: "'min(iw,360)':-2", description: 'mp4: all: video scale (ffmpeg scale argument)'},
         {name: :video_start_sec,      default: 10,                 description: 'mp4: all: start offset (seconds) of video preview'},
-        {name: :reencode_ffmpeg,      default: {},                 description: 'mp4: reencode: options to ffmpeg'},
+        {name: :reencode_ffmpeg,      default: {},                 description: 'mp4: reencode: options to ffmpeg, keys: `in`, `out`'},
         {name: :blend_keyframes,      default: 30,                 description: 'mp4: blend: # key frames'},
         {name: :blend_pauseframes,    default: 3,                  description: 'mp4: blend: # pause frames'},
         {name: :blend_transframes,    default: 5,                  description: 'mp4: blend: # transition blend frames'},

data/lib/aspera/preview/terminal.rb

@@ -11,15 +11,22 @@ require 'aspera/environment'
 module Aspera
   module Preview
     module Backend
-      # provides image pixels scaled to terminal
+      # Base decoder that rescales image data to the current terminal geometry.
       class Base
+        # @param reserve [Integer] number of terminal rows reserved for non-image output
+        # @param double [Boolean] when `true`, render two image rows in one terminal row
+        # @param font_ratio [Float] terminal font aspect ratio: height divided by width
         def initialize(reserve:, double:, font_ratio:)
           @reserve = reserve
           @height_ratio = double ? 2.0 : 1.0
           @font_ratio = font_ratio
         end
         Aspera.require_method!(:terminal_pixels)
-        # compute scaling to fit terminal
+        # Compute output dimensions that fit inside the terminal while preserving aspect ratio.
+        #
+        # @param rows [Integer] source image height in pixels
+        # @param columns [Integer] source image width in pixels
+        # @return [Array<Integer>] scaled width and height for terminal rendering
         def terminal_scaling(rows, columns)
           (term_rows, term_columns) = IO.console.winsize || [24, 80]
           term_rows = [term_rows - @reserve, 2].max
@@ -29,22 +36,30 @@ module Aspera
       end
 
       class RMagick < Base
+        # Initialize the RMagick-backed decoder for a binary image payload.
+        #
+        # @param blob [String] encoded image binary content
+        # @param kwargs [Hash] forwarding options accepted by [`initialize`](lib/aspera/preview/terminal.rb:16)
         def initialize(blob, **kwargs)
           super(**kwargs)
-          # do not require statically, as the package is optional
+          # Load lazily because this dependency is optional.
           require 'rmagick' # https://rmagick.github.io/index.html
           @image = Magick::ImageList.new.from_blob(blob)
         end
 
+        # Decode the image and return RGB pixels scaled for terminal rendering.
+        #
+        # @return [Array<Array<Array<Integer>>>] rows of `[red, green, blue]` pixel triplets
         def terminal_pixels
-          # quantum depth is 8 or 16, see: `magick xc: -format "%q" info:`
+          # ImageMagick channel depth is typically 8 or 16 bits.
+          # See: `magick xc: -format "%q" info:`
           shift_for_8_bit = Magick::MAGICKCORE_QUANTUM_DEPTH - 8
-          # get all pixel colors, adjusted for Rainbow
+          # Extract RGB values and normalize them to 8-bit channels for Rainbow.
           pixel_colors = []
           @image.scale(*terminal_scaling(@image.rows, @image.columns)).each_pixel do |pixel, col, row|
             pixel_rgb = [pixel.red, pixel.green, pixel.blue]
             pixel_rgb = pixel_rgb.map{ |color| color >> shift_for_8_bit} unless shift_for_8_bit.eql?(0)
-            # init 2-dim array
+            # Initialize the destination 2D pixel matrix row by row.
             pixel_colors[row] ||= []
             pixel_colors[row][col] = pixel_rgb
           end
@@ -53,12 +68,19 @@ module Aspera
       end
 
       class ChunkyPNG < Base
+        # Initialize the ChunkyPNG-backed decoder for a PNG payload.
+        #
+        # @param blob [String] PNG binary content
+        # @param kwargs [Hash] forwarding options accepted by [`initialize`](lib/aspera/preview/terminal.rb:16)
         def initialize(blob, **kwargs)
           super(**kwargs)
           require 'chunky_png'
           @png = ::ChunkyPNG::Image.from_blob(blob)
         end
 
+        # Resize the PNG using nearest-neighbor sampling and return RGB pixel rows.
+        #
+        # @return [Array<Array<Array<Integer>>>] rows of `[red, green, blue]` pixel triplets
         def terminal_pixels
           src_w = @png.width
           src_h = @png.height
@@ -75,7 +97,7 @@ module Aspera
               sx = (dx * x_ratio).floor
               sx = src_w - 1 if sx >= src_w
               rgba = @png.get_pixel(sx, sy)
-              # ChunkyPNG stores as 0xRRGGBBAA; extract 8-bit channels
+              # ChunkyPNG stores pixels as 0xRRGGBBAA; extract 8-bit RGB channels.
               pixel_colors[dy][dx] = %i[r g b].map{ |i| ::ChunkyPNG::Color.send(i, rgba)}
             end
           end
@@ -84,19 +106,21 @@ module Aspera
       end
     end
 
-    # Display a picture in the terminal.
-    # Either use coloured characters or iTerm2 protocol.
+    # Render an image for terminal output.
+    # Uses either colored text blocks or the iTerm2 inline-image protocol when available.
     class Terminal
-      # Rainbow only supports 8-bit colors
-      # env vars to detect terminal type
+      # Rainbow only supports 8-bit color values.
+      # Environment variables inspected to detect compatible terminal implementations.
       TERM_ENV_VARS = %w[TERM_PROGRAM LC_TERMINAL].freeze
-      # terminal names that support iTerm2 image display
+      # Terminal identifiers known to support the iTerm2 inline-image protocol.
       ITERM_NAMES = %w[iTerm WezTerm mintty].freeze
-      # TODO: retrieve terminal font ratio using some termcap ?
-      # ratio = font height / font width
+      # Fallback font aspect ratio used to estimate how many image pixels fit in a character cell.
+      # Ratio = font height / font width.
       DEFAULT_FONT_RATIO = 32.0 / 14.0
       private_constant :TERM_ENV_VARS, :ITERM_NAMES, :DEFAULT_FONT_RATIO
       class << self
+        # Render an image blob for display in the current terminal.
+        #
         # @param blob       [String]  The image as a binary string
         # @param text       [Boolean] `true` to display the image as text, `false` to use iTerm2 if supported
         # @param reserve    [Integer] Number of lines to reserve for other text than the image
@@ -124,7 +148,7 @@ module Aspera
             return iterm_display_image(blob) if iterm_supported?
             raise 'Cannot decode picture.'
           end
-          # now generate text
+          # Convert decoded pixels into terminal glyphs.
           text_pixels = []
           pixel_colors.each_with_index do |row_data, row|
             next if double && (row.odd? || row.eql?(pixel_colors.length - 1))
@@ -140,11 +164,14 @@ module Aspera
           return text_pixels.join
         end
 
-        # display image in iTerm2
+        # Build the iTerm2 inline-image escape sequence.
         # https://iterm2.com/documentation-images.html
+        #
+        # @param blob [String] image binary content
+        # @return [String] escape sequence that displays the image inline
         def iterm_display_image(blob)
           # image = Magick::ImageList.new.from_blob(blob)
-          # parameters for iTerm2 image display
+          # Parameters accepted by the iTerm2 inline-image protocol.
           arguments = {
             inline:              1,
             preserveAspectRatio: 1,
@@ -152,12 +179,15 @@ module Aspera
             # width:               image.columns,
             # height:              image.rows
           }.map{ |k, v| "#{k}=#{v}"}.join(';')
-          # \a is BEL, \e is ESC : https://github.com/ruby/ruby/blob/master/doc/syntax/literals.rdoc#label-Strings
-          # escape sequence for iTerm2 image display
+          # `\a` is BEL and `\e` is ESC.
+          # See: https://github.com/ruby/ruby/blob/master/doc/syntax/literals.rdoc#label-Strings
+          # Return the full escape sequence expected by iTerm2-compatible terminals.
           return "\e]1337;File=#{arguments}:#{Base64.strict_encode64(blob)}\a"
         end
 
-        # @return [Boolean] true if the terminal supports iTerm2 image display
+        # Detect whether the current terminal supports iTerm2 inline images.
+        #
+        # @return [Boolean] `true` when the current terminal advertises iTerm2 image support
         def iterm_supported?
           TERM_ENV_VARS.each do |env_var|
             return true if ITERM_NAMES.any?{ |term| ENV[env_var]&.include?(term)}