Move docs to markdown and improve them

WyattBlue · Jul 29, 2023 · f37e7f6 · f37e7f6
1 parent 0258459
commit f37e7f6
Show file tree

Hide file tree

Showing 11 changed files with 176 additions and 132 deletions.
diff --git a/.gitignore b/.gitignore
@@ -13,6 +13,8 @@ site/src/blog/*.html
 !site/src/blog/index.html
 site/src/docs/subcommands/*.html
 !site/src/docs/subcommands/index.html
+site/src/docs/*.html
+!site/src/docs/index.html
 
 # Python Generated Files
 __pycache__/

diff --git a/auto_editor/lang/palet.py b/auto_editor/lang/palet.py
@@ -726,9 +726,14 @@ def palet_assert(expr: object, msg: str | bool = False) -> None:
     if expr is not True:
         raise MyError("AssertError" if msg is False else f"AssertError: {msg}")
 
+
 def palet_system(cmd: str) -> bool:
     import subprocess
-    return (result := subprocess.run(cmd, shell=True).returncode) == 0
+
+    try:
+        return subprocess.run(cmd, shell=True).returncode == 0
+    except Exception:
+        return False
 
 
 ###############################################################################

diff --git a/site/blog_gen.nim b/site/blog_gen.nim
@@ -4,6 +4,7 @@ import std/strformat
 
 type
   PragmaKind = enum
+    normalType,
     blogType,
     explainerType,
 
@@ -269,24 +270,33 @@ proc convert(pragma: PragmaKind, file: string, path: string) =
     error(lexer, "head: expected end ---")
 
   var output = ""
-  if pragma == blogType:
-    output = &"""{{{{ comp.header "{title}" }}}}
+  case pragma:
+    of blogType:
+      output = &"""{{{{ comp.header "{title}" }}}}
 <body>
 {{{{ comp.nav }}}}
 <section class="section">
 <div class="container">
     <h1>{title}</h1>
     <p class="author-date">{author}&nbsp;&nbsp;&nbsp;{date}</p>
 """
-  else:
-    output = &"""{{{{ comp.header "{title}" }}}}
+    of normalType:
+      output = &"""{{{{ comp.header "{title}" }}}}
+<body>
+{{{{ comp.nav }}}}
+<section class="section">
+<div class="container">
+"""
+    of explainerType:
+      output = &"""{{{{ comp.header "{title}" }}}}
 <body>
 {{{{ comp.nav }}}}
 <section class="section">
 <div class="container">
     <h2 class="left">{title}</h2>
 """
 
+
   let f = open(path, fmWrite)
   f.write(output)
 
@@ -389,5 +399,8 @@ proc convert(pragma: PragmaKind, file: string, path: string) =
 for file in walkFiles("src/blog/*.md"):
   convert(blogType, file, file.changeFileExt("html"))
 
+for file in walkFiles("src/docs/*.md"):
+  convert(normalType, file, file.changeFileExt("html"))
+
 for file in walkFiles("src/docs/subcommands/*.md"):
   convert(explainerType, file, file.changeFileExt("html"))
diff --git a/site/src/docs/gpu.html b/site/src/docs/gpu.html
diff --git a/site/src/docs/gpu.md b/site/src/docs/gpu.md
@@ -0,0 +1,33 @@
+---
+title: GPU Acceleration
+---
+
+# GPU Acceleration
+## Does Auto-Editor support GPU acceleration?
+Yes, enable it by linking a version of FFmpeg with GPU acceleration to Auto-Editor and setting the appropriate video codec.
+Use `--my-ffmpeg` or `--ffmpeg-location` option for linking.
+
+### How do I enable GPU acceleration on FFmpeg?
+Compile FFmpeg with the appropriate flags and follow the relevant instructions.
+ * [NVidia](https://docs.nvidia.com/video-technologies/video-codec-sdk/ffmpeg-with-nvidia-gpu/). See [Supported GPUs](https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new)
+ * AMD [Ubuntu+Windows](https://askubuntu.com/a/1132191)
+
+FFmpeg [Compilation Guide](https://trac.ffmpeg.org/wiki/CompilationGuide)
+ * [MacOS](https://trac.ffmpeg.org/wiki/CompilationGuide/macOS)
+ * [Windows](https://trac.ffmpeg.org/wiki/CompilationGuide/CrossCompilingForWindows)
+ * [Ubuntu / Debian / Mint](https://trac.ffmpeg.org/wiki/CompilationGuide/Ubuntu)
+ * [CentOS / RHEL / Fedor](https://trac.ffmpeg.org/wiki/CompilationGuide/Centos)
+ * [Generic Compiling Guide](https://trac.ffmpeg.org/wiki/CompilationGuide/Generic)
+
+Remember to set the export codec in auto-editor. `auto-editor --video-codec`.
+Note that the resulting build is legally undistributable.
+
+### Will enabling GPU acceleration make auto-editor go faster?
+If you want to export to a certain codec that is compatible with your GPU, yes, in some cases, it will go noticeably faster, albeit with some slight quality loss.
+
+However, in most other cases, GPU acceleration won't do anything since analyze and creating new media files are mostly CPU bound. Given how relatively complex enabling GPU acceleration is, it is not recommend for most users.
+
+---
+### Further Reading
+ * [What is a GPU](https://www.intel.com/content/www/us/en/products/docs/processors/what-is-a-gpu.html)
+ * [What's the difference between a CPU and a GPU](https://blogs.nvidia.com/blog/2009/12/16/whats-the-difference-between-a-cpu-and-a-gpu/)
diff --git a/site/src/docs/range_syntax.html b/site/src/docs/range_syntax.html
diff --git a/site/src/docs/range_syntax.md b/site/src/docs/range_syntax.md
@@ -0,0 +1,72 @@
+---
+title: Time Range Syntax
+---
+
+# Time Range Syntax
+The `--add-in`, `--cut-out`, `--mark-as-loud`, `--mark-as-silent` options use time range syntax.
+
+It describes two numbers, the start and end point, separated by a singe comma `,`. The start number is inclusive, while the end number is exclusive.
+
+```
+# This will cut out the first frame: frame 0
+auto-editor example.mp4 --cut-out 0,1
+
+# This will cut out five frames: frames 0, 1, 2, 3, 4
+# frame 5 will still exist because the end point is exclusive
+auto-editor example.mp4 --cut-out 0,5
+
+# Cuts out 60 frames
+auto-editor example.mp4 --cut-out 10,70
+
+# No frame will be cut here
+auto-editor example.mp4 --cut-out 0,0
+```
+
+## Variables
+Time range syntax allows two variables: `start` and `end`
+`start` is the same as `0`
+`end` is the length of the timeline before any edits are applied.
+
+```
+# This will mark everything in the beginning as silent
+auto-editor example.mp4 --mark-as-silent start,300
+
+# This will mark everything besides the beginning as loud
+auto-editor example.mp4 --mark-as-loud 300,end
+
+# This will cut out everything
+auto-editor example.mp4 --cut-out start,end
+```
+
+## Units
+The default unit is the timeline's timebase. Since specifying the range in this unit can sometimes be annoying. You can use the `sec` unit to specify the range in seconds. (Note that the seconds range will be rounded to the nearest timebase to you don't have any more precision than usual).
+
+```
+# Cut out the first 10 seconds.
+auto-editor example.mp4 --cut-out start,10secs
+```
+You can also use `s`, `sec`, `second`, or `seconds`, depending on your preference.
+
+## Multiple Ranges
+All options discussed here support specifying multiple ranges at the same time. Overlapping ranges are allowed.
+
+```
+auto-editor example.mp4 --cut-out 0,20 45,60, 234,452
+```
+
+## Negative Indexes
+Negative numbers can be used to count down starting from the end.
+ * `-60,end` selects the last 60 frames
+ * `1sec,-30secs` selects from the first second, to the last 30 seconds from the end.
+
+## Speed for Range
+The `--set-speed-for-range` option has a slight twist on time range syntax. It accepts three numbers. `speed`, `start`, and `end`, separated by commas. `speed` can be a decimal number, but not negative. `start` and `end` work as described above.
+
+```
+# Set the speed to 2x from frame 0 to frame 29
+auto-editor example.mp4 --set-speed-for-range 2,0,30
+
+# Set the speed to 0.5x
+auto-editor example.mp4 --set-speed-for-range 0.5,start,end
+```
+
diff --git a/site/src/docs/supported_media.html b/site/src/docs/supported_media.html
diff --git a/site/src/docs/supported_media.md b/site/src/docs/supported_media.md
@@ -0,0 +1,23 @@
+---
+title: Supported Media
+---
+
+# Supported Media
+Auto-Editor supports a wide range of media formats thanks to ffmpeg. Listed below is what is and is not allowed.
+
+## What's allowed
+ * Media with only audio streams
+ * Media with only video streams
+ * Media with video, audio, subtile, embedded images, and data streams
+
+## What isn't
+ * Media with only subtitle/data streams.
+ * Media with video or audio streams longer than 24 hours
+ * Video streams whose total number of frames exceeds a 60fps 24 hour video
+ * Audio streams whose total number of samples exceeds a 192kHz 24 hour video
+
+Using specific codecs/containers depends on which ffmpeg program auto-editor uses.
+
+---
+### Footnotes
+The terms "stream" and "track" are used interchangeably.
diff --git a/site/src/docs/windows.html b/site/src/docs/windows.html
diff --git a/site/src/docs/windows.md b/site/src/docs/windows.md
@@ -0,0 +1,23 @@
+---
+title: Using Auto-Editor on Windows
+---
+
+# Using Auto-Editor on Windows
+## Recommended Shell and Terminal
+Use the [Windows Terminal](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701) app with PowerShell when running auto-editor commands. Using the CMD shell isn't impossible, but you'll have to escape commands differently than shown in the docs.
+
+### Shell vs. Terminal
+A terminal is a GUI program that manages shells. It handles features like scrolling through history, and copy paste. A shell is a program that interacts with OS. Having a modern terminal means the terminal will look beautiful instead of ugly. Having a modern shell installed makes scripting much easier.
+
+CMD is the older terminal/shell that Windows keeps around for compatibily reasons. I recommend using Windows Terminal plus Powershell instead.
+
+## Running Auto-Editor on Many Files
+Auto-Editor doesn't have an option that batch processes files, but you can achieve the same effect with a simple PowerShell script.
+
+```
+# Save to a new file with a ".ps1" extension
+$files = "C:\Users\WyattBlue\MyDir\"
+foreach ($f in Get-ChildItem $files) {
+  auto-editor $(Join-Path -Path $files -ChildPath $f)
+}
+```