Merge pull request #481 from amiaopensource/delete_script

delete `get_recipe_list` script

index.html

@@ -19,6 +19,7 @@
     <a href="#about"><div class="contents-list">About this resource</div></a>
     <div id="toggle-expand-collapse-all" class="contents-list">Expand/collapse all recipes</div>
     <a href="#basics"><div class="contents-list">FFmpeg basics</div></a>
+    <a href="#troubleshooting"><div class="contents-list">Troubleshooting common issues</div></a>
     <a href="#concepts"><div class="contents-list">Advanced FFmpeg concepts</div></a>
     <a href="#rewrap"><div class="contents-list">Change container (rewrap)</div></a>
     <a href="#transcode"><div class="contents-list">Change codec (transcode)</div></a>
@@ -47,11 +48,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">
@@ -104,6 +105,45 @@
         <p class="link"></p>
       </div>
       <!-- End Streaming vs. Saving -->
+      
+      <!-- Troubleshooting Common Issues -->
+      <label class="recipe" for="troubleshooting">Troubleshooting Common Issues</label>
+       <input type="checkbox" id="troubleshooting">
+      <div class="hiding"> 
+          <h5>Troubleshooting Common Issues</h5>
+          <p>There are many common issues you may encounter when using FFmpeg. This section is here to provide some possible explanations and solutions. For more general solutions to issues regarding download, installation, and other possible questions or issues, please refer to the <a href="https://ffmpeg.org/faq.html">FFmpeg FAQ</a>.
+<p>Before delving into some specific error messages and what may cause them, there are a few general tips you can follow to help make sure your files are doing what you want them to.
+First, always check that the output file actually opens, plays, looks, and/or sounds the way you intended it to. It is possible that FFmpeg will create an output file that, on the surface, looks correct, but upon further inspection, there may be inconsistencies with the codec, extension, or other file information, depending on what you intended to do with the file. 
+Second, always be certain that the file extension you are using for your output files is the intended extension. Within FFmpeg, certain extensions default to certain codecs, such as <code>.mp4</code> encoding to H.264. You always want to make sure that your extension coincides with your intended codec. A list of extensions and codec defaults can be found <a href="https://amiaopensource.github.io/ffmprovisr/#codec-defaults">here</a>.</p>
+<h5>General Error Messages</h5>
+<h5>"Error: No such file or directory"</h5> 
+          <p><img src="img/directory_error_example.png" alt="no such file or directory error message"></p> 
+          <p>There are a few reasons why this error may be appearing. First, check to make sure that you are in the correct directory. It can be easy to lose track of where your files are actually stored, especially on a personal computer. If you are working on a personal computer, the easiest way to do this is to check where your files are. When working with macOS, for example, files are often stored in the Downloads or Documents folders. To change your directory from home to this specific directory, use the command <code>cd</code> followed by your desired folder. For a folder named Downloads, it would look like this:  <code>cd $HOME/Downloads</code></p> 
+          <p>After you have ensured that you are in the correct directory, and the error is still occurring, check that your argument is formatted correctly. If you are copying and pasting from a separate document or ffmprovisr directly, there may be typos or missing spaces. 
+If the error message includes other parts of the command, such as a flag, that indicates where your typo or missing space may be, as in this example, where the <code>-c</code> flag has not been separated from the file name:</p>
+          <p><img src="img/typo_space_error.png" alt="missing space typo error message"></p>
+          <p>Sometimes, when copying and pasting, even if the command is free of typos and correctly formatted, the error may occur. When this happens, it is best to attempt to rewrite the command from scratch in the command line.</p>
+          <h5>"Could not find tag for codec"</h5>
+        <p><img src="img/codec_rewrap_error.png" alt="codec rewrap error message"></p>
+        <p>This error message comes when attempting to rewrap a file that has audio or video codecs that are incompatible with the output files extension. This is discussed briefly at the bottom of the rewrap recipe, where it is suggested that you look through possible transcoding recipes. Being able to transcode the file into the correct codec for rewrapping before you run the rewrap command is ideal, but if you are not fully familiar with transcoding and are sure that the extension you are using for your output file will automatically encode the streams with the correct codecs, removing the <code>-c copy</code> flag will solve this error.</p>
+<h5>"Killed"</h5>
+          <p>"Killed" does not appear as a normal error message, but will show up during the output of the command, and the point at which it appears can vary. Sometimes, after you run a command it will be "killed" immediately, only making it through one frame before terminating, as in this example:</p>
+        <p><img src="img/first_frame_killed.png" alt="command killed at first frame example"></p>
+        <p>Killed may appear when the file you are working with exceeds the memory capacity of your server. If you are working on a remote server, this can be solved by increasing your memory capacity. If you are working on a local server that should have enough storage and it is still occurring, check that your version of FFmpeg is up to date, and try to avoid running commands with other programs that also require a large amount of memory space at the same time.</p> 
+<h5>Filters</h5>
+          <p>When using filters, there are a handful of errors that may pop up. While this section certainly does not cover them all, below you will find a couple of possible errors and what could be causing them.</p>
+        <h5>"Error splitting argument list: option not found"</h5>
+        <p><img src="img/error_splitting_argument.png" alt="error splitting argument error message example"></p>
+        <p>This error often comes from a mistake in the formatting of the command. If you are trying to use certain filters, such as <b>“hflip,vflip,”</b> you may need to remove the quotation marks, as they are not mandatory for certain filter arguments. This is not always the case, as quotation marks are used with filtergraphs to indicate the beginning and end of a filtergraph. Forgetting to remove the quotation marks on certain filters may prompt FFmpeg to run the command as a filtergraph, resulting in an error message like this one:</p>
+        <p><img src="img/filtergraph_error.png" alt="filtergraph error message"></p>
+        <p>To avoid this error, check whether the filter you are using requires quotation marks or not. Similar to other errors, oftentimes writing out the entire command, rather than copying and pasting, is beneficial to check for these formatting errors.</p>
+        <p>Also between the two example errors above, there is one difference that can be helpful to pinpoint when trying to troubleshoot. For the first error, “option not found” refers to the use of quotation marks in a filter that did not require them, thus making the command an unidentifiable option to FFmpeg and making it impossible to differentiate between certain flags in the argument. For the second error, “filter not found” also refers to the use of quotation marks in a command that did not require them, but this time FFmpeg read the argument as a filtergraph due to the quotation marks. For more information regarding filtergraphs, check out the <a href="https://amiaopensource.github.io/ffmprovisr/#filtergraphs">filtergraph section</a>.</p>
+        <h5>Streams</h5>
+        <p>In addition to the possible errors encountered due to typos and improper formatting, some error messages can occur due to inconsistencies with the file streams. Inside each file, there can be numerous streams for audio, video, subtitles, and other file information.</p>
+        <p>It is possible, when creating output files, to accidentally attempt to use a filter while also asking FFmpeg to copy the file streams directly. Be mindful of where you are trying to put a file’s streams, as filtering and streaming cannot be done together due to the re-encoding of streams that filters must do.</p>
+        <p><img src="img/filter_and_stream_error.png" alt="filter and stream error message"></p>
+        <p>To help you further understand issues regarding streams, check out the <a href="https://amiaopensource.github.io/ffmprovisr/#stream-mapping">stream mapping section.</a></p>
+      <!-- End Troubleshooting Common Issues --> 
     </div>
     <div class="well">
 
@@ -225,7 +265,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>
@@ -680,22 +720,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>
@@ -1409,6 +1450,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">
@@ -1468,7 +1546,7 @@
         <dt>-i <em>input_file</em></dt><dd>path, name and extension of the input file</dd>
         <dt>-filter:v idet</dt><dd>This calls the <a href="https://ffmpeg.org/ffmpeg-filters.html#idet" target="_blank">idet (detect video interlacing type) filter</a>.</dd>
         <dt>-f null</dt><dd>Video is decoded with the <code>null</code> muxer. This allows video decoding without creating an output file.</dd>
-        <dt>-</dt><dd>FFmpeg syntax requires a specified output, and <code>-</code> is just a place holder. No file is actually created.</dd>
+        <dt>-</dt><dd>The FFmpeg syntax requires a specified output, and <code>-</code> prints the output to the screen (STDOUT), rather than creating a file.</dd>
       </dl>
       <p class="link"></p>
     </div>
@@ -1984,7 +2062,7 @@
         <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>-f null</dt><dd>Video is decoded with the <code>null</code> muxer. This allows video decoding without creating an output file.</dd>
-        <dt>-</dt><dd>FFmpeg syntax requires a specified output, and <code>-</code> is just a place holder. No file is actually created.</dd>
+        <dt>-</dt><dd>The FFmpeg syntax requires a specified output, and <code>-</code> prints the output to the screen (STDOUT), rather than creating a file.</dd>
       </dl>
       <p class="link"></p>
     </div>
@@ -2003,7 +2081,7 @@
         <dt>-report</dt><dd>Dump full command line and console output to a file named <em>ffmpeg-YYYYMMDD-HHMMSS.log</em> in the current directory. It also implies <code>-loglevel verbose</code>.</dd>
         <dt>-i <em>input_file</em></dt><dd>path, name and extension of the input file</dd>
         <dt>-f null</dt><dd>Video is decoded with the <code>null</code> muxer. This allows video decoding without creating an output file.</dd>
-        <dt>-</dt><dd>FFmpeg syntax requires a specified output, and <code>-</code> is just a place holder. No file is actually created.</dd>
+        <dt>-</dt><dd>The FFmpeg syntax requires a specified output, and <code>-</code> prints the output to the screen (STDOUT), rather than creating a file.</dd>
       </dl>
       <p class="link"></p>
     </div>
@@ -2090,7 +2168,7 @@
         <dt>-i <em>input_file</em></dt><dd>path, name and extension of the input file</dd>
         <dt>-map 0:v:0</dt><dd>designated the first video stream as the stream on which to perform this hash generation operation. <code>-map 0</code> can be used to run the operation on all streams.</dd>
         <dt>-f hash -hash md5</dt><dd>produce a checksum hash, and set the hash algorithm to md5. See the official <a href="https://ffmpeg.org/ffmpeg-formats.html#hash" target="_blank">documentation on hash</a> for other algorithms.</dd>
-        <dt>-</dt><dd>FFmpeg syntax requires a specified output, and <code>-</code> is just a place holder. No file is actually created.</dd>
+        <dt>-</dt><dd>The FFmpeg syntax requires a specified output, and <code>-</code> prints the output to the screen (STDOUT), rather than creating a file.</dd>
       </dl>
       <p class="link"></p>
     </div>
@@ -2110,7 +2188,7 @@
         <dt>-i <em>input_file</em></dt><dd>path, name and extension of the input file</dd>
         <dt>-map 0</dt><dd>map ALL streams from input file to output. If you omit this, ffmpeg chooses only the first "best" (*) stream: 1 for audio, 1 for video (not all streams).</dd>
         <dt>-f streamhash -hash md5</dt><dd>produce a checksum hash per-stream, and set the hash algorithm to md5. See the official <a href="https://www.ffmpeg.org/ffmpeg-formats.html#streamhash-1" target="_blank">documentation on streamhash</a> for other algorithms and more details.</dd>
-        <dt>-</dt><dd>FFmpeg syntax requires a specified output, and <code>-</code> is just a place holder. No file is actually created. Choose an output filename to write the hashcode lines into a textfile.</dd>
+        <dt>-</dt><dd>The FFmpeg syntax requires a specified output, and <code>-</code> prints the output to the screen (STDOUT), rather than creating a file. Choose an output filename to write the hashcode lines into a textfile.</dd>
         <dt>-v quiet</dt><dd>(Optional) Disables FFmpeg's processing output. With this option it's easier to see the text output of the hashes.</dd>
       </dl>
       <p>The output looks like this, for example (1 video, 2 audio streams):

readme.md

@@ -53,8 +53,6 @@ ffmpeg command n-1
 ffmpeg command n
 ```
 
-The used [one-liner](scripts/get_recipe_list) is in the `scripts` folder.
-
 ## How do I contribute?
 
 You are welcome to edit the codebase yourself, or just supply the information and ask it to be added to the site.

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

scripts/ffmprovisr

@@ -6,8 +6,10 @@
 if [[ "$(uname -s)" = "Darwin" ]] ; then
     if ping -c 1 amiaopensource.github.io >/dev/null 2>&1 ; then
         ffmprovisr_path='https://amiaopensource.github.io/ffmprovisr/'
+    elif [[ -d /usr/local/Cellar/ffmprovisr ]] ; then
+        ffmprovisr_path=$(find /usr/local/Cellar/ffmprovisr -name 'index.html' | sort -M | tail -n1)
     else
-        ffmprovisr_path=$(find /usr/local/Cellar/ffmprovisr -iname 'index.html' | sort -M | tail -n1)
+        ffmprovisr_path=$(find /opt/homebrew/Cellar/ffmprovisr -name 'index.html' | sort -M | tail -n1)
     fi
     open "${ffmprovisr_path}"
 elif [[ "$(uname -s)" = "Linux" ]] ; then

scripts/get_recipe_list

@@ -1 +0,0 @@
-curl https://amiaopensource.github.io/ffmprovisr/ -s | grep -E '<h5>.*</h5>|<p><code>.*</code></p>' | sed 's/.*<code>\(.*\)<\/code>/\1/' | sed 's/.*<h5>\(.*\)<\/h5>/# \1/' | grep -v '\*\*\*' | sed -e 's/<[^>]*>//g'