video_transcoding 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 87623b30297fe1ddbce3986414be06e26c569b60
-  data.tar.gz: 5676f1d6d2167969670e434ee920135ec04646f5
+  metadata.gz: 21bb797cefd32f9ceb7968e597bbd4ae228f9ea5
+  data.tar.gz: 76f86e86734d67d1d4880ddd9fee3460eb651016
 SHA512:
-  metadata.gz: 560af874e2847c118be25ec00fd9ee9197a3c41c09960c89ead29084ec62775fdb0ab93911a4a34be52af2e9ce86182077ef998667a2178d20755064b1db6e86
-  data.tar.gz: 6caf5107757863ac5da7d91a76119473394cbe81f8be1c8b5e4da06d9466c6fd8b41303522afe1652423656e7ad510a729cea0c2101b68cad045cb2c7a88acbb
+  metadata.gz: ff95b3ffa523b27d68eac0da8bce8c2cf22b25ff4fa5ad6c812bf64af55fdf190341d22e9adc55810a021d586b5c5d5d0701320103c5dcbc9b127fb7afdae4f5
+  data.tar.gz: 9a79522dd3531e905c60e370a34e56f13989beae695aa36b861137c790095bbf8fa66754248581a484ceb76e8dfe9d14fec1c4062e066d9beabedbbf2a2a3dcc

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 which achieves those goals.
+What makes these tools unique is the [special ratecontrol system](#explanation) which achieves 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.
 
@@ -31,6 +31,7 @@ Even if you don't try any of my tools, you may find this "README" document helpf
 * [Rationale](#rationale)
 * [Usage](#usage)
 * [Guide](#guide)
+* [Explanation](#explanation)
 * [FAQ](#faq)
 * [History](#history)
 * [Feedback](#feedback)
@@ -39,7 +40,7 @@ Even if you don't try any of my tools, you may find this "README" document helpf
 
 ## Installation
 
-My Video Transcoding tools are designed to work on OS X, Linux and Windows. They're packaged as a Gem and require Ruby version 2.0 or later. See "[Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/)" if you don't have the proper version on your platform.
+My Video Transcoding tools are designed to work on macOS, Linux and Windows. They're packaged as a Gem and require Ruby version 2.0 or later. See "[Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/)" if you don't have the proper version on your platform.
 
 Use this command to install the package: 
 
@@ -70,7 +71,7 @@ You can download the command line version of HandBrake, called `HandBrakeCLI`, h
 
 <https://handbrake.fr/downloads2.php>
 
-On OS X, the other dependencies can be easily installed via [Homebrew](http://brew.sh/), an add-on package manager:
+On macOS, the other dependencies can be easily installed via [Homebrew](http://brew.sh/), an add-on package manager:
 
     brew install ffmpeg
     brew install mkvtoolnix
@@ -87,7 +88,7 @@ On Windows, it's best to search the Web for the appropriate binary or add-on pac
 
 <https://gist.github.com/JMoVS/75f3c6b344648deef59bc761e5e5a0e6>
 
-When installing `HandBrakeCLI` or other downloaded programs, make sure the executable binary is in a directory listed in your `PATH` environment variable. On Unix-style systems like OS X and Linux, that directory might be `/usr/local/bin`.
+When installing `HandBrakeCLI` or other downloaded programs, make sure the executable binary is in a directory listed in your `PATH` environment variable. On Unix-style systems like macOS and Linux, that directory might be `/usr/local/bin`.
 
 ## Rationale
 
@@ -411,7 +412,7 @@ I have four rules when preparing my own media for transcoding:
 
 #### Why MakeMKV?
 
-* It runs on most desktop computer platforms like OS X, Windows and Linux. There's even a free version available to try before you buy.
+* It runs on most desktop computer platforms like macOS, Windows and Linux. There's even a free version available to try before you buy.
 
 * It was designed to decrypt and extract a video track, usually the main feature of a disc and convert it into a single Matroska format `.mkv` file. And it does this really, really well.
 
@@ -553,6 +554,53 @@ The path is first deleted from the `queue.txt` file and then passed as an argume
 
 These examples are written in Bash and only supply crop values. But almost any scripting language can be used and any option can be changed on a per input basis.
 
+## Explanation
+
+### How my special ratecontrol system works
+
+When using `transcode-video`, you might notice two lines in the console output containing something like this:
+
+```
+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.
+
+The average bitrate (ABR) mode in x264 is normally used to target a specific bitrate. But the ABR algorithm often sacrifices quality in order to maintain that bitrate. Getting acceptable quality with ABR requires multiple passes through the input, a process too slow for many people. And even multiple-pass ABR won't provide sufficient quality for some 1080p video input when bitrate targets are as low as `6000` Kbps.
+
+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`.
+
+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.
+
+So I set the target CRF value to `1`, the best possible "lossy" quality. Normally this would produce a huge output bitrate but I also manipulate the video buffering verifier (VBV) model within x264 to constrain that bitrate.
+
+Typically, the VBV model limits the output bitrate to a generous `25000` Kbps for video playback on devices like the Apple TV or Roku. But I reduce the VBV maximum bitrate (`vbv-maxrate`) to my target, e.g. `6000` Kbps for 1080p output.
+
+With this approach, x264 chooses the lowest CRF value, and therefore the highest quality, which fits below that ceiling, even if that's usually not a a CRF value of `1`.
+
+But manipulating only CRF and `vbv-maxrate` will not produce high enough quality output in some cases. Why? Sometimes you need a much higher bitrate for complex or difficult to encode passages than what is allowed by `vbv-maxrate`.
+
+Along with the target CRF value of `1`, I set a maximum CRF (`crf-max`) value of `25`, raising the minimum quality. This allows `vbv-maxrate` to become a "soft" ceiling so that the output bitrate can exceed the target when necessary to maintain that quality.
+
+But just adding a maximum CRF value is not enough. When under pressure to fit within all these constraints, x264 will sometimes generate a single, but still noticeable, very low quality frame. Why? Even though `crf-max` is set to `25`, individual frames can still use a higher quantizer value (QP) of much less quality.
+
+As part of the encoding process, x264 calculates a quantizer value (QP) for each macroblock within a frame of video. A QP is represented by a number from `0` to `69` with lower values indicating higher quality.
+
+So I set a maximum quantizer (`qpmax`) value of `34`, again raising the minimum quality. The occasional bad frame is still there, but it's no longer noticeable because it's now of sufficient quality to blend in with the others.
+
+There's a final change required for the VBV model. I need to set the VBV buffer size (`vbv-bufsize`) so that my previous adjustment of `vbv-maxrate` is honored by x264. Otherwise the encoder will just ignore the VBV.
+
+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.
+
 ## FAQ
 
 ### Should I worry about all these `VBV underflow` warnings?
@@ -573,6 +621,12 @@ My ratecontrol system can't be applied with the current version of the x265 enco
 
 But support also requires equivalent quality at a smaller size when using my rate control system. And performance is an issue. While speed continues to improve, the x265 encoder is still considerably slower than the current H.264 system.
 
+You can try _experimental_ HEVC transcoding now with an advanced option:
+
+    transcode-video --handbrake-option encoder=x265 "/path/to/Movie.mkv"
+
+But use this _only_ with `HandBrakeCLI` nightly builds from September 29, 2016, or later.
+
 ### What about hardware-based video transcoding?
 
 Using hardware with [Intel Quick Sync Video](https://en.wikipedia.org/wiki/Intel_Quick_Sync_Video) instead of software like x264 is certainly faster. HandBrake even supports that hardware on some platforms. However, my default ratecontrol system can't be applied to existing hardware encoders because they lack API to change the necessary settings.
@@ -609,6 +663,16 @@ For a few problematic videos, I have to apply options like `--force-rate 23.976
 
 ## History
 
+### [0.12.1](https://github.com/donmelton/video_transcoding/releases/tag/0.12.1)
+
+Friday, November 4, 2016
+
+* Modify `transcode-video` to enable the `--quick` option only for the x264 video encoder and enable my special ratecontrol system only for the x264 and x265 encoders.
+* Update the "README" document to:
+    * Revise the H.265 answer in the "FAQ" section to show how you can try _experimental_ HEVC transcoding now.
+    * Use new canonical "macOS" name.
+    * Add "Explanation" section describing how my special ratecontrol system works.
+
 ### [0.12.0](https://github.com/donmelton/video_transcoding/releases/tag/0.12.0)
 
 Friday, October 14, 2016
@@ -657,7 +721,7 @@ Friday, May 6, 2016
 
 * Add resolution-specific qualifiers to the `--target` option in `transcode-video`. This allows different video bitrate targets for inputs with different resolutions. For example, you can use `--target 1080p=6500` alone to change the target for Blu-ray Discs and not DVDs. Or you could combine that with `--target 480p=2500` to affect both resolutions. Via [ #68](https://github.com/donmelton/video_transcoding/pull/68) from [@turley](https://github.com/turley).
 * Fix a bug in `transcode-video` where video bitrate targets were not reset when the `--small` or `--small-video` options followed the `--target` option on the command line.
-* Fix a bug where `query-handbrake-log` would fail for `time` or `speed` on OS X or Linux when parsing .log files created on Windows. This was due to a regular expression not expecting a carriage return (CR) before a line feed (LF), i.e. a Windows-style line ending (CRLF). Via [ #67](https://github.com/donmelton/video_transcoding/issues/67) from [@lambdan](https://github.com/lambdan).
+* Fix a bug where `query-handbrake-log` would fail for `time` or `speed` on macOS or Linux when parsing .log files created on Windows. This was due to a regular expression not expecting a carriage return (CR) before a line feed (LF), i.e. a Windows-style line ending (CRLF). Via [ #67](https://github.com/donmelton/video_transcoding/issues/67) from [@lambdan](https://github.com/lambdan).
 
 ### [0.9.0](https://github.com/donmelton/video_transcoding/releases/tag/0.9.0)
 

data/bin/transcode-video

@@ -255,7 +255,7 @@ HERE
       @vbr_quality                = nil
       @encoder_options            = {}
       @disable_encoder_options    = []
-      @handbrake_options          = {'encoder-preset' => 'medium'}
+      @handbrake_options          = {}
       @disable_handbrake_options  = []
       @temporary                  = nil
     end
@@ -873,6 +873,35 @@ HERE
 
       handbrake_options[anamorphic] = nil unless @handbrake_options.has_key? 'custom-anamorphic'
 
+      unless @handbrake_options.has_key? 'rate'
+        rate = '30'
+        fps = media.info[:fps]
+
+        if fps == 29.97
+          if media.info[:mpeg2]
+            rate = '23.976'
+          else
+            unless  @handbrake_options.has_key? 'deinterlace' or
+                    @handbrake_options.has_key? 'decomb' or
+                    @handbrake_options.has_key? 'detelecine'
+              handbrake_options['deinterlace'] = nil
+            end
+          end
+        elsif media.info[:mpeg2]
+          case fps
+          when 23.976, 24.0, 25.0
+            rate = fps.to_s
+          end
+        end
+
+        handbrake_options['rate'] = rate
+        handbrake_options['pfr'] = nil if rate == '30'
+      end
+
+      encoder = @handbrake_options.fetch('encoder', 'x264')
+      return unless encoder == 'x264' or encoder == 'x265'
+      handbrake_options['encoder-preset'] = 'medium'
+
       if width > 1920 or height > 1080
         encoder_level = '5.1'
         vbv_maxrate = @vbv_maxrate_2160p
@@ -887,7 +916,7 @@ HERE
         vbv_maxrate = @vbv_maxrate_480p
       end
 
-      case @handbrake_options.fetch('encoder', 'x264')
+      case encoder
       when 'x264'
         handbrake_options['encoder-profile'] = 'high'
         handbrake_options['encoder-level'] = encoder_level
@@ -929,38 +958,15 @@ HERE
         handbrake_options['quality'] = @vbr_quality.to_s.gsub(/\.0+$/, '') unless @vbr_quality.nil?
       end
 
-      if @quick and @handbrake_options.fetch('encoder-preset', 'medium') == 'medium'
+      if  @quick and
+          @handbrake_options.fetch('encoder-preset', 'medium') == 'medium' and
+          encoder == 'x264'
         encoder_options['ref']          = '1'
         encoder_options['weightp']      = '1'
         encoder_options['subme']        = '6'
         encoder_options['mixed-refs']   = '0'
         encoder_options['rc-lookahead'] = '30'
       end
-
-      unless @handbrake_options.has_key? 'rate'
-        rate = '30'
-        fps = media.info[:fps]
-
-        if fps == 29.97
-          if media.info[:mpeg2]
-            rate = '23.976'
-          else
-            unless  @handbrake_options.has_key? 'deinterlace' or
-                    @handbrake_options.has_key? 'decomb' or
-                    @handbrake_options.has_key? 'detelecine'
-              handbrake_options['deinterlace'] = nil
-            end
-          end
-        elsif media.info[:mpeg2]
-          case fps
-          when 23.976, 24.0, 25.0
-            rate = fps.to_s
-          end
-        end
-
-        handbrake_options['rate'] = rate
-        handbrake_options['pfr'] = nil if rate == '30'
-      end
     end
 
     def resolve_crop(media)

data/lib/video_transcoding/version.rb

@@ -5,5 +5,5 @@
 #
 
 module VideoTranscoding
-  VERSION = '0.12.0'
+  VERSION = '0.12.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: video_transcoding
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - Don Melton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-15 00:00:00.000000000 Z
+date: 2016-11-05 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Video Transcoding is a package of tools to transcode, inspect