Merge pull request #469 from MobyGamer/deinterlace_updates

Update deinterlacing methods to current best practices

index.html

@@ -63,7 +63,7 @@
       <p><a href="https://datapraxis.github.io/sourcecaster/" target="_blank">The Sourcecaster</a>: an app that helps you use the command line to work through common challenges that come up when working with digital primary sources.</p>
       <p><a href="https://pugetsoundandvision.github.io/micropops/" target="_blank">Micropops</a>: One liners and automation tools from Moving Image Preservation of Puget Sound</p>
       <p><a href="https://amiaopensource.github.io/cable-bible/" target="_blank">Cable Bible</a>: A Guide to Cables and Connectors Used for Audiovisual Tech</p>
-      <p><a href="https://eaasi.gitlab.io/qemu-qed/" target="_blank">QEMU QED</a>: instructions for using QEMU (Quick EMUlator), a command line application for computer emulation and virtualization</p>
+      <p><a href="https://eaasi.gitlab.io/program_docs/qemu-qed/" target="_blank">QEMU QED</a>: instructions for using QEMU (Quick EMUlator), a command line application for computer emulation and virtualization</p>
       <p><a href="https://amiaopensource.github.io/ffmpeg-artschool/" target="_blank">ffmpeg-artschool</a>: An AMIA workshop featuring scripts, exercises, and activities to make art using FFmpeg</p>
     </div>
 
@@ -108,6 +108,18 @@
     <div class="well">
 
     <h2 id="concepts">Learn about more advanced FFmpeg concepts</h2>
+    <!-- Loop usage explanation -->
+    <label class="recipe" for="batch-loop">Batch and Loop script usage</label>
+    <input type="checkbox" id="batch-loop">
+    <div class="hiding">
+      <h5>Batch and Loop script usage</h5>
+      <p><code>ffmpeg -nostdin -i <em>input_file</em> ...</code></p>
+      <p>One of the frequent uses of FFmpeg is to run batch commands within loops to, for example, generate access files for an entire collection at once.</p>
+      <p>When running an FFmpeg command within a loop it is often necessary to use the <code>-nostdin</code> flag prior to the input in order to ensure successful execution of the commands. This is needed to override FFmpeg's default behavior of enabling interaction on standard input which can result in errors as loop inputs are fed to the ongoing command.</p>
+      <p class="link"></p>
+    </div>
+    <!-- End loop usage explanation -->
+
     <!-- Codec Defaults explanation -->
     <label class="recipe" for="codec-defaults">Codec defaults</label>
     <input type="checkbox" id="codec-defaults">
@@ -213,7 +225,7 @@
         The new container you are rewrapping to is defined by the filename extension used here, e.g. .mkv, .mp4, .mov.</dd>
       </dl>
       <h4>Important caveat</h4>
-      <p>It may not be possible to rewrap a file's contents to a new container without re-encoding one or more of the streams within (that is, the video, audio, and subtitle tracks). Some containers can only contain streams of a certain encoding type: for example, the .mp4 container does not support uncompressed audio tracks. (In practice .mp4 goes hand-in-hand with a H.264-encoded video stream and an AAC-encoded video stream, although other types of video and audio streams are possible). Another example is that the Matroska container does not allow data tracks; see the <a href="#mkv-to-mp4">MKV to MP4 recipe</a>.</p>
+      <p>It may not be possible to rewrap a file's contents to a new container without re-encoding one or more of the streams within (that is, the video, audio, and subtitle tracks). Some containers can only contain streams of a certain encoding type: for example, the .mp4 container does not support uncompressed audio tracks. (In practice .mp4 goes hand-in-hand with a H.264-encoded video stream and an AAC-encoded video stream, although other types of video and audio streams are possible). Another example is that the Matroska container does not allow data tracks.</p>
       <p>In such cases, FFmpeg will throw an error. If you encounter errors of this kind, you may wish to consult the <a href="#transcode">list of transcoding recipes</a>.</p>
       <p class="link"></p>
     </div>
@@ -492,7 +504,6 @@
       <h5>Transcode to Ogg/Theora</h5>
       <p><code>ffmpeg -i <em>input_file</em> -acodec libvorbis -b:v 690k <em>output_file</em></code></p>
       <p>This command takes an input file and transcodes it to Ogg/Theora in an .ogv wrapper with 690k video bitrate.</p>
-      <p><strong>Note:</strong> FFmpeg must be installed with support for Ogg Theora. If you are using Homebrew, you can check with <code>brew info ffmpeg</code> and then update it with <code>brew upgrade ffmpeg --with-theora --with-libvorbis</code> if necessary.</p>
       <dl>
         <dt>ffmpeg</dt><dd>starts the command</dd>
         <dt>-i <em>input file</em></dt><dd>path, name and extension of the input file</dd>
@@ -1093,16 +1104,18 @@
     <div class="hiding">
       <h5>Join files together</h5>
       <p><code>ffmpeg -f concat -i mylist.txt -c copy <em>output_file</em></code></p>
-      <p>This command takes two or more files of the same file type and joins them together to make a single file. All that the program needs is a text file with a list specifying the files that should be joined. However, it only works properly if the files to be combined have the exact same codec and technical specifications. Be careful, FFmpeg may appear to have successfully joined two video files with different codecs, but may only bring over the audio from the second file or have other weird behaviors. Don’t use this command for joining files with different codecs and technical specs and always preview your resulting video file!</p>
+      <p>This command takes two or more files of the same file type and joins them together to make a single file. All that the program needs is a text file with a list specifying the files that should be joined. If possible, run the command from the same directory where the files and the text file reside. Otherwise you'll have to use <code>-safe 0</code>, see below for more information. However, it only works properly if the files to be combined have the exact same codec and technical specifications. Be careful, FFmpeg may appear to have successfully joined two video files with different codecs, but may only bring over the audio from the second file or have other weird behaviors. Don’t use this command for joining files with different codecs and technical specs and always preview your resulting video file!</p>
       <dl>
         <dt>ffmpeg</dt><dd>starts the command</dd>
         <dt>-f concat</dt><dd>forces ffmpeg to concatenate the files and to keep the same file format</dd>
         <dt>-i <em>mylist.txt</em></dt><dd>path, name and extension of the input file. Per the <a href="https://ffmpeg.org/ffmpeg-formats.html#Options" target="_blank">FFmpeg documentation</a>, it is preferable to specify relative rather than absolute file paths, as allowing absolute file paths may pose a security risk.<br>
-        This text file contains the list of files to be concatenated and should be formatted as follows:
-        <pre>file '<em>./first_file.ext</em>'
-  file '<em>./second_file.ext</em>'
+        This text file contains the list of files (without their absolute path) to be concatenated and should be formatted as follows:
+<pre>
+  file '<em>first_file.ext</em>'
+  file '<em>second_file.ext</em>'
   . . .
-  file '<em>./last_file.ext</em>'</pre>
+  file '<em>last_file.ext</em>'
+</pre>
   In the above, <strong>file</strong> is simply the word "file". Straight apostrophes ('like this') rather than curved quotation marks (‘like this’) must be used to enclose the file paths.<br>
   <strong>Note:</strong> If specifying absolute file paths in the .txt file, add <code>-safe 0</code> before the input file.<br>
   e.g.: <code>ffmpeg -f concat -safe 0 -i mylist.txt -c copy <em>output_file</em></code></dd>
@@ -1396,6 +1409,43 @@
     </div>
     <!-- ends Deinterlace video -->
 
+    <!-- Deinterlace video fields -->
+    <label class="recipe" for="deinterlace_fields">Deinterlace video fields to frames</label>
+    <input type="checkbox" id="deinterlace_fields">
+    <div class="hiding">
+      <h5>Deinterlace video fields to frames</h5>
+      <p><code>ffmpeg -i <em>input_file</em> -c:v libx264 -vf "idet,bwdif,format=yuv420p" <em>output_file</em></code></p>
+      <p>This command takes an interlaced input file and outputs a deinterlaced H.264 MP4, with each field separated into its own frame.  This is preferred for interlaced video that contains a lot of motion, as the double-rate output preserves the visual cadence of the source material.</p>
+      <dl>
+        <dt>ffmpeg</dt><dd>starts the command</dd>
+        <dt>-i <em>input file</em></dt><dd>path, name and extension of the input file</dd>
+        <dt>-c:v libx264</dt><dd>tells FFmpeg to encode the video stream as H.264</dd>
+        <dt>-vf</dt><dd>video filtering will be used (<code>-vf</code> is an alias of <code>-filter:v</code>)</dd>
+        <dt>"</dt><dd>start of filtergraph (see below)</dd>
+        <dt>idet</dt><dd>detect interlaced video field order<br>
+         <a href="https://ffmpeg.org/ffmpeg-filters.html#idet" target="_blank">idet</a> will try to detect if the video is interlaced, and if so, what the order of the fields are (top-field-first, or bottom-field-first).  This is done to ensure the output of the deinterlacing filter is correct.</dd>
+        <dt>bwdif</dt><dd>deinterlacing filter (‘Bob Weaver Deinterlacing Filter’)<br>
+         By default, <a href="https://ffmpeg.org/ffmpeg-filters.html#bwdif-1" target="_blank">bwdif</a> will output one frame for each field, matching the visual cadence of interlaced video. </dd>
+        <dt>,</dt><dd>separates filters</dd>
+        <dt>format=yuv420p</dt><dd>chroma subsampling set to 4:2:0<br>
+        By default, <code>libx264</code> will use a chroma subsampling scheme that is the closest match to that of the input. This can result in Y′C<sub>B</sub>C<sub>R</sub> 4:2:0, 4:2:2, or 4:4:4 chroma subsampling. QuickTime and most other non-FFmpeg based players can’t decode H.264 files that are not 4:2:0, therefore it’s advisable to specify 4:2:0 chroma subsampling.</dd>
+        <dt>"</dt><dd>end of filtergraph</dd>
+        <dt><em>output file</em></dt><dd>path, name and extension of the output file</dd>
+      </dl>
+      <p><code>"idet,bwdif,format=yuv420p"</code> is an FFmpeg <a href="https://trac.ffmpeg.org/wiki/FilteringGuide#FiltergraphChainFilterrelationship" target="_blank">filtergraph</a>. Here the filtergraph is made up of one filter chain, which is itself made up of the three filters (separated by the comma).<br>
+      The enclosing quote marks are necessary when you use spaces within the filtergraph, e.g. <code>-vf "idet, bwdif, format=yuv420p"</code>, and are included above as an example of good practice.</p>
+      <p><strong>Note:</strong> bwdif also supports the older method of outputting one frame for each frame (thereby halving the number of output frames per second) with the syntax <code>bwdif=mode=send_frame</code>.  This can be used when the presentation device is not capable of reproducing 50 (PAL) or 60 (NTSC) frames per second.</p>
+      <p>For more H.264 encoding options, see the latter section of the <a href="#transcode_h264">encode H.264 command</a>.</p>
+      <div class="sample-image">
+        <h2>Example</h2>
+        <p>Before and after deinterlacing with bwdif:</p>
+        <img src="img/interlaced_video_fields.png" alt="VLC screenshot of original interlaced video">
+        <img src="img/deinterlaced_video_frames.png" alt="VLC screenshot of deinterlaced video">
+      </div>
+      <p class="link"></p>
+    </div>
+    <!-- ends Deinterlace video fields -->
+
     <!-- Inverse telecine -->
     <label class="recipe" for="inverse-telecine">Inverse telecine</label>
     <input type="checkbox" id="inverse-telecine">
@@ -2368,7 +2418,6 @@
     <input type="checkbox" id="ocr_on_top">
     <div class="hiding">
       <h5>Plays video with OCR on top</h5>
-      <p>Note: ffmpeg must be compiled with the tesseract library for this script to work (<code>--with-tesseract</code> if using the <code>brew install ffmpeg</code> method).</p>
       <p><code>ffplay input_file -vf "ocr,drawtext=fontfile=/Library/Fonts/Andale Mono.ttf:text=%{metadata\\\:lavfi.ocr.text}:fontcolor=white"</code></p>
       <dl>
         <dt>ffplay</dt><dd>starts the command</dd>
@@ -2392,7 +2441,6 @@
     <input type="checkbox" id="ffprobe_ocr">
     <div class="hiding">
       <h5>Exports OCR data to screen</h5>
-      <p>Note: FFmpeg must be compiled with the tesseract library for this script to work (<code>--with-tesseract</code> if using the <code>brew install ffmpeg</code> method)</p>
       <p><code>ffprobe -show_entries frame_tags=lavfi.ocr.text -f lavfi -i "movie=<em>input_file</em>,ocr"</code></p>
       <dl>
         <dt>ffprobe</dt><dd>starts the command</dd>

readme.md

@@ -173,7 +173,7 @@ Last updated: 2019-12-11
 
 [The Cable Bible](https://amiaopensource.github.io/cable-bible/): A Guide to Cables and Connectors Used for Audiovisual Tech  
 [FFCommand_Engine](https://github.com/ColorlabMD/FFCommand_Engine): a tool for easier use of FFmpeg binaries  
-[QEMU QED](https://eaasi.gitlab.io/qemu-qed): instructions for using QEMU (Quick EMUlator), a command line application for computer emulation and virtualization  
+[QEMU QED](https://eaasi.gitlab.io/program_docs/qemu-qed/): instructions for using QEMU (Quick EMUlator), a command line application for computer emulation and virtualization  
 [Script Ahoy](http://dd388.github.io/crals/): Community Resource for Archivists and Librarians Scripting  
 [sourcecaster](https://datapraxis.github.io/sourcecaster/): helps you use the command line to work through common challenges that come up when working with digital primary sources.
 

scripts/ffmprovisr

@@ -4,17 +4,12 @@
 # connected to the Web, and the local version otherwise.
 
 if [[ "$(uname -s)" = "Darwin" ]] ; then
-    default_browser=$(plutil -convert json ~/Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist -r -o - | grep https -b1 | tail -n1 | cut -d'"' -f4)
     if ping -c 1 amiaopensource.github.io >/dev/null 2>&1 ; then
         ffmprovisr_path='https://amiaopensource.github.io/ffmprovisr/'
     else
         ffmprovisr_path=$(find /usr/local/Cellar/ffmprovisr -iname 'index.html' | sort -M | tail -n1)
     fi
-    if [[ -n "${default_browser}" ]] ; then
-        open -b "${default_browser}" "${ffmprovisr_path}"
-    else
-        open "${ffmprovisr_path}"
-    fi
+    open "${ffmprovisr_path}"
 elif [[ "$(uname -s)" = "Linux" ]] ; then
     if ping -c 1 amiaopensource.github.io >/dev/null 2>&1 ; then
         ffmprovisr_path='https://amiaopensource.github.io/ffmprovisr/'