video_transcoding 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb79007469f914ec85593c97f2bd67a8a1cae2fe3dcae7803982ec5149493382
-  data.tar.gz: 0c9ea74a41bd0e699816588f0036e49f2628bd034207f7a85c3ba6eb3f94209e
+  metadata.gz: 695200c196efef71d738e5db7027d7b767751dfa09dc9c1033a35873ff19f9bb
+  data.tar.gz: 1eeddcc6b991a23c5e8d78843655862b2ca5774ff90c94cf7726cf23b39b46ff
 SHA512:
-  metadata.gz: a3a7c6a45257009851f648568b2d700da25f87f079cfd9d1fc78721af6404225b58cfb63f77938f36b0bc0b6cedf0e132422e2761c23ee8fdfd2f3f6ed2676d6
-  data.tar.gz: 4b0e1430d6da378ad6876409452d4bfec4324d07aa6147e4a2fe5a313e9beaaf99a33c6091c5590a8e0feb44943b1520b1c09509f6b04269d122ac0c725199f0
+  metadata.gz: 35882e7a8f9384633941b8a93b084cc09b1d3b0f4c140aa4cac4fc0cdb88737426461c058eb84c34719c680a0b0b99d60559404de13686a5f9225da429cd9255
+  data.tar.gz: 62f40bdecf719ce99d60a3f885be636a2b1af800e862782069c96d806a7d7da3f6af447cea54e40817d9e53393fc9955e542b866c20f39f40e83d59f0e4a2944

data/README.md

@@ -6,7 +6,7 @@ Tools to transcode, inspect and convert videos.
 
 Hi, I'm [Don Melton](http://donmelton.com/). I created these tools to transcode my collection of Blu-ray Discs and DVDs into a smaller, more portable format while remaining high enough quality to be mistaken for the originals.
 
-What makes these tools unique is the [special ratecontrol system](#explanation) which achieves those goals.
+What makes these tools unique are the [two ratecontrol systems](#explanation) which achieve those goals.
 
 This package is based on my original collection of [Video Transcoding Scripts](https://github.com/donmelton/video-transcoding-scripts) written in Bash. While still available online, those scripts are no longer in active development. Users are encouraged to install this Ruby Gem instead.
 
@@ -274,6 +274,8 @@ Or use this command to make main audio output as a single track but still allow
 
     transcode-video --audio-width main=surround "/path/to/Movie.mkv"
 
+Please note that tracks transcoded to stereo AAC format, including the main track, are output in matrix-encoded [Dolby Pro Logic II](https://en.wikipedia.org/wiki/Dolby_Pro_Logic) surround format when the original input is multi-channel surround sound. This means that even though the AAC stereo track contains only two discrete channels, it can be decoded as multiple channels. So Dolby Digital AC-3 format is not actually required for surround sound output.
+
 If possible, audio is first passed through in its original format, providing that format is either AC-3 or AAC. This hardly ever works for Blu-ray Discs but it often will for DVDs and other random videos.
 
 However, you can still copy audio tracks and maintain their original format, provided HandBrake and your selected file format support it:
@@ -557,6 +559,22 @@ These examples are written in Bash and only supply crop values. But almost any s
 
 ## Explanation
 
+### A tale of two ratecontrol systems
+
+What is a ratecontrol sytem? It's how a video encoder decides on the amount of bits to allocate for a specific frame.
+
+My `transcode-video` tool has two different ratecontrol systems available to control the size and quality of output video. The special, or default, ratecontrol system is designed to deliver consistent quality, while the average bitrate (ABR) ratecontrol system, enabled via the `--abr` option, is designed to produce a predictable output size.
+
+Both ratecontrol systems are modified versions of what is commonly called a constrained variable bitrate (CVBR) mode. Which means they both allow bitrate to vary per frame but still constrain that bitrate.
+
+My special ratecontrol system leverages the constant quality ratecontrol system already within the x264 video encoder, an algorithm which uses a constant ratefactor (CRF) to target a specific quality instead of a bitrate.
+
+My average bitrate (ABR) ratecontrol system modifies the ABR algorithm already within x264 which targets a specific bitrate, constraining it to produce better overall quality.
+
+The target video bitrate for both systems is automatically determined by `transcode-video` using the resolution of the input. For example, the default target for 1080p output is `6000` Kbps, which is about one-fifth the video bitrate found on a typical Blu-ray Disc.
+
+While both systems deliver high quality, they sometimes have different visual characteristics.
+
 ### How my special ratecontrol system works
 
 When using `transcode-video`, you might notice two lines in the console output containing something like this:
@@ -565,16 +583,13 @@ When using `transcode-video`, you might notice two lines in the console output c
 options: vbv-maxrate=6000:vbv-bufsize=12000:crf-max=25:qpmax=34
 
 quality: 1.00 (RF)
-
 ```
 
 These are actually the settings used by my special ratecontrol system to configure the x264 video encoder within HandBrake.
 
-My system attempts to produce the highest possible video quality near a target bitrate. That target is automatically determined by `transcode-video` using the resolution of the input. For example, the default target for 1080p output is `6000` Kbps, which is about one-fifth the video bitrate found on a typical Blu-ray Disc.
+This system attempts to produce the highest possible video quality near a target bitrate using a constant ratefactor (CRF) to specify quality. A CRF is represented by a number from `0` to `51` with lower values indicating higher quality. The special value of `0` is for lossless output.
 
-The average bitrate (ABR) mode in x264 is normally used to target a specific bitrate. Instead, I leverage the constant quality ratecontrol system in x264. This algorithm uses a constant ratefactor (CRF) to target a specific quality instead of a bitrate. A CRF is represented by a number from `0` to `51` with lower values indicating higher quality. The special value of `0` is for lossless output.
-
-Unfortunately, the output bitrate is extremely unpredictable when using this CRF-based system. Typically, people pick a middle-level CRF value as their quality target and just hope for the best. This is what most of the presets built into HandBrake do, choosing a CRF of `20` or `22`.
+Unfortunately, the output bitrate is extremely unpredictable when using the x264's default CRF-based system. Typically, people pick a middle-level CRF value as their quality target and just hope for the best. This is what most of the presets built into HandBrake do, choosing a CRF of `20` or `22`.
 
 But such a strategy can result in output larger than its input or, worse, output too low in quality to be mistaken for that input.
 
@@ -598,7 +613,29 @@ There's a final change required for the VBV model. I need to set the VBV buffer
 
 It's safe to set `vbv-bufsize` anywhere in the range from one half to twice that of `vbv-maxrate`. However, that larger `vbv-bufsize` value produces an output bitrate closest to, on average, that of the target. So, if `vbv-maxrate` is `6000` Kbps, then I set `vbv-bufsize` to `12000` Kbps.
 
-All these settings are essential for transcoding Blu-ray Discs and DVDs into a smaller, more portable format while remaining high enough quality to be mistaken for the originals. And `transcode-video` handles that configuration automatically for you.
+### How my average bitrate (ABR) ratecontrol system works
+
+When using `transcode-video` with the `--abr` option, you might notice two lines in the console output containing something like this:
+
+```
+options: vbv-maxrate=9000:vbv-bufsize=12000:nal-hrd=vbr
+
+bitrate: 6000 kbps, pass: 0
+```
+
+This ABR ratecontrol system attempts to produce a predictable output size while still maintaining high quality by manipulating the video buffering verifier (VBV) model within the x264 video encoder.
+
+As mentioned before, the VBV model typically allows bitrates to peak as high as `25000` Kbps during playback on most devices. But I constrain the VBV maximum bitrate (`vbv-maxrate`) to only 1.5 times that of the target, i.e. to just `9000` Kbps when the target bitrate is `6000` Kbps for 1080p output.
+
+It seems counterintuitive, but constraining the maximum bitrate prevents too much bitrate being wasted on complex or difficult to encode passages at the expense of quality elsewhere. This is because with an average bitrate algorithm, when the peaks get too high then the valleys get too low.
+
+As with the default ratecontrol system, I need to set the VBV buffer size (`vbv-bufsize`) so that my previous adjustment of `vbv-maxrate` won't be ignored by x264. So, if `vbv-maxrate` is `9000` Kbps, then I set `vbv-bufsize` to `12000` Kbps.
+
+This VBV model manipulation is exactly the same strategy used by streaming services such as Netflix.
+
+The final setting, `nal-hrd=vbr`, doesn't actually affect ratecontrol. This is a x264 option signaling Hypothetical Reference Decoder (HRD) information, meaning that it adds the VBV maximum bitrate value as metadata to the output video. Which is useful for certain streaming environments and media tools.
+
+And this information is safe to include since my ABR ratecontrol implementation will, by design, never exceed the maximum bitrate. Which is something the default ratecontrol system cannot promise.
 
 ## FAQ
 
@@ -652,6 +689,20 @@ For a few problematic videos, I have to apply options like `--force-rate 23.976
 
 ## History
 
+### [0.20.0](https://github.com/donmelton/video_transcoding/releases/tag/0.20.0)
+
+Monday, June 18, 2018
+
+* Now require `HandBrakeCLI` version 1.0.0 or later. Not only does this change make for easier testing, but it allows removal of many capability-detection hacks needed to support older versions. My thanks again to all the users who provided positive feedback about this online!
+* Relax frame rate control in `transcode-video` so that the options `--rate=30` and `--pfr` are no longer passed to `HandBrakeCLI` for most non-DVD videos. This means that the peak frame rate will no longer be limited to `30` FPS, allowing camera-generated videos to retain their original frame rates. However, the old behavior can be restored for those videos by adding `--limit-rate 30` to your `transcode-video` command line.
+* Modify `transcode-video` to no longer pass `--encoder-preset=medium` to `HandBrakeCLI` since that's the default behavior anyway. However, adding `--preset medium` to your `transcode-video` command line still does so.
+* Modify `transcode-video` to no longer pass a named audio encoder to `HandBrakeCLI` in order to select AAC, i.e. `ca_aac` or `av_aac`, since AAC is the default audio format anyway. However, adding the `--aac-encoder` option to your `transcode-video` command line still allows an explicit choice.
+* Modify `transcode-video` to substitute "analyse" for the x264 option called "partitions" when invoked with the `--quick` or `--veryquick` options. This is done to better match the archaic internal name used by HandBrake. It has no effect on actual transcoding behavior.
+* Add `-n` as a shortcut alias for the `--dry-run` option in `transcode-video`. This is the same shortcut alias used in `rsync` and `make`.
+* Expand the "Explanation" section of the "README" document to describe both the special, or default, ratecontrol system and the average bitrate (ABR) ratecontrol system, enabled via the `--abr` option.
+* Add clarification to the "README" document that stereo AAC tracks can also include surround audio information in matrix-encoded Dolby Pro Logic II format.
+* Fix spelling of "suppress" in the `--help` output of `query-handbrake-log`. Thanks, [@chrisridd](https://github.com/chrisridd)! Via [ #205](https://github.com/donmelton/video_transcoding/pull/205).
+
 ### [0.19.0](https://github.com/donmelton/video_transcoding/releases/tag/0.19.0)
 
 Saturday, January 27, 2018

data/bin/query-handbrake-log

@@ -39,7 +39,7 @@ r,  ratefactor      average P-frame quantizer for transcoding
 
 Options:
     --reverse       reverse direction of sort
-    --tabular       use tab character as field delimiter and surpress labels
+    --tabular       use tab character as field delimiter and suppress labels
 
 -v, --verbose       increase diagnostic information
 -q, --quiet         decrease     "           "

data/bin/transcode-video

@@ -53,7 +53,7 @@ Output options:
                     import chapter names from `.csv` text file
                       (in NUMBER,NAME format, e.g. "1,Intro")
     --no-log        don't write log file
-    --dry-run       don't transcode, just show `HandBrakeCLI` command and exit
+-n, --dry-run       don't transcode, just show `HandBrakeCLI` command and exit
 
 Quality options:
     --abr           use constrained average bitrate (ABR) ratecontrol
@@ -95,7 +95,6 @@ Video options:
                       (`23.976` applied automatically for some inputs)
     --limit-rate FPS
                     set peak-limited video frame rate
-                      (`30` applied automatically for most inputs)
     --filter NAME[=SETTINGS]
                     apply `HandBrakeCLI` video filter with optional settings
                       (`deinterlace` applied automatically for some inputs)
@@ -316,7 +315,7 @@ HERE
       end
 
       opts.on('--no-log')             { @log = false }
-      opts.on('--dry-run')            { @dry_run = true }
+      opts.on('-n', '--dry-run')      { @dry_run = true }
 
       opts.on '--abr' do
         @use_abr = true
@@ -876,13 +875,13 @@ HERE
           height = adjusted_height
         end
       else
-        anamorphic = HandBrake.auto_anamorphic
+        anamorphic = 'auto-anamorphic'
       end
 
       handbrake_options[anamorphic] = nil unless @handbrake_options.has_key? 'custom-anamorphic'
 
       unless @handbrake_options.has_key? 'rate'
-        rate = '30'
+        rate = nil
         fps = media.info[:fps]
 
         if fps == 29.97
@@ -902,18 +901,14 @@ HERE
           end
         end
 
-        handbrake_options['rate'] = rate
-
-        if rate == '30'
-          handbrake_options['pfr'] = nil
-        else
+        unless rate.nil?
+          handbrake_options['rate'] = rate
           handbrake_options['cfr'] = nil
         end
       end
 
       encoder = @handbrake_options.fetch('encoder', 'x264')
       return unless encoder =~ /^x264(?:_10bit)?$/ or encoder =~ /^x265(?:_1[026]bit)?$/
-      handbrake_options['encoder-preset'] = 'medium'
 
       if width > 1920 or height > 1080
         encoder_level = '5.1'
@@ -979,7 +974,7 @@ HERE
       if  (@quick or @veryquick) and
           @handbrake_options.fetch('encoder-preset', 'medium') == 'medium' and
           encoder =~ /^x264(?:_10bit)?$/
-        encoder_options['partitions']   = 'none'
+        encoder_options['analyse']      = 'none'
         encoder_options['ref']          = '1'
         encoder_options['bframes']      = '1'     if @veryquick
         encoder_options['rc-lookahead'] = '30'
@@ -1071,7 +1066,7 @@ HERE
         if copy or (info[:format] == 'AAC' and info[:channels] <= 2.0)
           encoders << 'copy'
         else
-          @aac_encoder ||= HandBrake.aac_encoder
+          @aac_encoder ||= ''
           encoders << @aac_encoder
         end
 
@@ -1127,7 +1122,8 @@ HERE
       end
 
       handbrake_options['audio'] = tracks.join(',')
-      handbrake_options['aencoder'] = encoders.join(',')
+      encoders = encoders.join(',')
+      handbrake_options['aencoder'] = encoders if encoders.gsub(/,/, '') != ''
       handbrake_options['audio-fallback'] = @ac3_encoder unless @copy_audio.empty?
       bitrates = bitrates.join(',')
       handbrake_options['ab'] = bitrates if bitrates.gsub(/,/, '') != ''

data/lib/video_transcoding/handbrake.rb

@@ -11,83 +11,20 @@ module VideoTranscoding
     COMMAND_NAME = 'HandBrakeCLI'
 
     def setup
-      Tool.provide(COMMAND_NAME, ['--preset-list']) do |output, status, _|
-        fail "#{COMMAND_NAME} failed during execution" unless status == 0
+      Tool.provide(COMMAND_NAME, ['--version']) do |output, status, _|
+        fail "#{COMMAND_NAME} version 1.0.0 or later required" unless status == 0
 
-        if output =~ /^HandBrake ([^h][^ ]+)/
-          version = $1
-          Console.info "#{$MATCH} found..."
-
-          unless  (version =~ /^([0-9]+)\.([0-9]+)/ and (($1.to_i * 100) + $2.to_i) >= 10) or
-                  (version =~ /^svn([0-9]+)/ and $1.to_i >= 6536)
-            fail "#{COMMAND_NAME} version 0.10.0 or later required"
-          end
+        unless output =~ /^HandBrake ([^h][^ ]+)/
+          Console.debug output
+          fail "#{COMMAND_NAME} version unknown"
         end
-      end
 
-      begin
-        IO.popen([Tool.use(COMMAND_NAME), '--version'], :err=>[:child, :out]) do |io|
-          if io.read =~ /^HandBrake ([^h][^ ]+)/
-            Console.info "#{$MATCH.strip} found..."
-          end
-        end
-      rescue SystemCallError => e
-        raise "#{COMMAND_NAME} failed during execution: #{e}"
+        Console.info "#{$MATCH.strip} found..."
       end
     end
 
     def command_name
       Tool.use(COMMAND_NAME)
     end
-
-    def auto_anamorphic
-      properties = Tool.properties(COMMAND_NAME)
-
-      unless properties.has_key? :auto_anamorphic
-        if help_text =~ /auto-anamorphic/
-          properties[:auto_anamorphic] = 'auto-anamorphic'
-        else
-          properties[:auto_anamorphic] = 'strict-anamorphic'
-        end
-      end
-
-      properties[:auto_anamorphic]
-    end
-
-    def aac_encoder
-      properties = Tool.properties(COMMAND_NAME)
-
-      unless properties.has_key? :aac_encoder
-        if help_text =~ /ca_aac/
-          properties[:aac_encoder] = 'ca_aac'
-        else
-          properties[:aac_encoder] = 'av_aac'
-        end
-      end
-
-      properties[:aac_encoder]
-    end
-
-    private
-
-    def help_text
-      properties = Tool.properties(COMMAND_NAME)
-
-      unless properties.has_key? :help_text
-        properties[:help_text] = ''
-
-        begin
-          IO.popen([Tool.use(COMMAND_NAME), '--help'], :err=>[:child, :out]) do |io|
-            properties[:help_text] = io.read
-          end
-        rescue SystemCallError => e
-          raise "#{COMMAND_NAME} help text unavailable: #{e}"
-        end
-
-        fail "#{COMMAND_NAME} failed during execution" unless $CHILD_STATUS.exitstatus == 0
-      end
-
-      properties[:help_text]
-    end
   end
 end

data/lib/video_transcoding/version.rb

@@ -5,5 +5,5 @@
 #
 
 module VideoTranscoding
-  VERSION = '0.19.0'
+  VERSION = '0.20.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: video_transcoding
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Don Melton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-28 00:00:00.000000000 Z
+date: 2018-06-19 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Video Transcoding is a package of tools to transcode, inspect
@@ -64,7 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.4
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Tools to transcode, inspect and convert videos.