fixes #475 (#476)

Clarification of documentation

index.html

@@ -47,11 +47,11 @@
       <h2 class="heading" id="about">About ffmprovisr</h2>
       <h3>Making FFmpeg Easier</h3>
       <p>FFmpeg is a powerful tool for manipulating audiovisual files. Unfortunately, it also has a steep learning curve, especially for users unfamiliar with a command line interface. This app helps users through the command generation process so that more people can reap the benefits of FFmpeg.</p>
-      <p>Each button displays helpful information about how to perform a wide variety of tasks using FFmpeg. To use this site, click on the task you would like to perform. A new window will open up with a sample command and a description of how that command works. You can copy this command and understand how the command works with a breakdown of each of the flags.</p>
+      <p>Each button displays helpful information about how to perform a wide variety of tasks using FFmpeg. To use this site, click on the task you would like to perform. You will jump to a single command or a list of related commands. Click on a command description, and the site will display a sample command as well as an explanation of how that command works with a breakdown of each of its flags (or options).</p>
       <p>This page does not have search functionality, but you can open all recipes (second option in the sidebar) and use your browser's search tool (often ctrl+f or cmd+f) to perform a keyword search through all recipes.</p>
       <h3>Tutorials</h3>
       <p>For FFmpeg basics, check out the program’s <a href="https://ffmpeg.org/" target="_blank">official website</a>.</p>
-      <p>For instructions on how to install FFmpeg on Mac, Linux, and Windows, refer to Reto Kromer’s <a href="https://avpres.net/FFmpeg/#ch1" target="_blank">installation instructions</a>.</p>
+      <p>For instructions on how to install FFmpeg on macOS, Linux, and Windows, refer to Reto Kromer’s <a href="https://avpres.net/FFmpeg/#ch1" target="_blank">installation instructions</a>.</p>
       <p>For Bash and command line basics, try the <a href="https://learnpythonthehardway.org/book/appendixa.html" target="_blank">Command Line Crash Course</a>. For a little more context presented in an ffmprovisr style, try <a href="https://explainshell.com/" target="_blank">explainshell.com</a>!</p>
       <h3>License</h3>
       <p class="license">
@@ -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>
@@ -668,22 +680,23 @@
     </div>
     <!-- ends SD to HD -->
 
-    <!-- Change display aspect ratio without re-encoding video-->
+    <!-- Change display aspect ratio without re-encoding -->
     <label class="recipe" for="change_DAR">Change display aspect ratio without re-encoding</label>
     <input type="checkbox" id="change_DAR">
     <div class="hiding">
-      <h5>Change Display Aspect Ratio without re-encoding video</h5>
-      <p><code>ffmpeg -i <em>input_file</em> -c:v copy -aspect 4:3 <em>output_file</em></code></p>
+      <h5>Change Display Aspect Ratio without re-encoding</h5>
+      <p><code>ffmpeg -i <em>input_file</em> -c:a copy -c:v copy -aspect 4:3 <em>output_file</em></code></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:a copy</dt><dd>Copy all mapped audio streams.</dd>
         <dt>-c:v copy</dt><dd>Copy all mapped video streams.</dd>
         <dt>-aspect 4:3</dt><dd>Change Display Aspect Ratio to <code>4:3</code>. Experiment with other aspect ratios such as <code>16:9</code>. If used together with <code>-c:v copy</code>, it will affect the aspect ratio stored at container level, but not the aspect ratio stored in encoded frames, if it exists.</dd>
         <dt><em>output_file</em></dt><dd>path, name and extension of the output file</dd>
       </dl>
       <p class="link"></p>
     </div>
-    <!-- ends Change display aspect ratio without re-encoding video -->
+    <!-- ends Change display aspect ratio without re-encoding -->
 
     <!-- Convert colorspace -->
     <label class="recipe" for="convert-colorspace">Convert colorspace of video</label>
@@ -1397,6 +1410,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">

recipes.txt

@@ -37,7 +37,7 @@ ffmpeg -i input_file -filter:v "hflip,vflip" -c:a copy output_file
 # Transform SD to HD with pillarbox
 ffmpeg -i input_file -filter:v "colormatrix=bt601:bt709, scale=1440:1080:flags=lanczos, pad=1920:1080:240:0" -c:a copy output_file
 # Change display aspect ratio without re-encoding
-ffmpeg -i input_file -c:v copy -aspect 4:3 output_file
+ffmpeg -i input_file -c:a copy -c:v copy -aspect 4:3 output_file
 # Convert colorspace of video
 ffmpeg -i input_file -c:v libx264 -vf colormatrix=src:dst output_file
 # Modify image and sound speed
@@ -92,6 +92,8 @@ ffmpeg -i input_file -af areverse,silenceremove=start_threshold=-57dB:start_dura
 ffmpeg -i input_file -c:v libx264 -filter:v "yadif, scale=1440:1080:flags=lanczos, pad=1920:1080:(ow-iw)/2:(oh-ih)/2, format=yuv420p" output_file
 # Deinterlace video
 ffmpeg -i input_file -c:v libx264 -vf "yadif,format=yuv420p" output_file
+# Deinterlace video fields to frames
+ffmpeg -i input_file -c:v libx264 -vf "idet,bwdif,format=yuv420p" output_file
 # Inverse telecine
 ffmpeg -i input_file -c:v libx264 -vf "fieldmatch,yadif,decimate" output_file
 # Set field order for interlaced video