Skip to content

Latest commit

 

History

History
49 lines (33 loc) · 2.82 KB

footnotes.md

File metadata and controls

49 lines (33 loc) · 2.82 KB

On footnotes

These are the footnotes for the ace-of-diamonds project. They serve as extended documentation to better understand why some choices were made, notably regarding ffmpeg flags and options.

Table of Contents

1. On OGG containers and OGX

OGG is a container. While the associated Vorbis codec is often contained within an OGG container, it can also be contained in other containers such as MKV.

Similarly, the OGG container can contain other streams, whether video or audio. The nomenclature then wants it to be called OGX ; yet, the same-ish headers and hexadecimal organization can be found within, which can lead to mistake on with another.

To avoid creating OGX « by mistake » (creating an OGG container embedding a video stream), it is necessary to use the -vn ffmpeg flag to strip non-audio streams.

2. On the choice of Bash

Bash is often mockingly considered as a read-only language. This probably stems from the versatility of its uses as well as its heavily fragmented userspace.

As the Google Shellguide put it: If you are writing a script that is more than 100 lines long, or that uses non-straightforward control flow logic, you should rewrite it in a more structured language now. Bear in mind that scripts grow. Rewrite your script early to avoid a more time-consuming rewrite at a later date.

The present author has already tried to use a ffmpeg wrapper in a more maintainable language, but this attempt failed, notably for a relative lack of flexibility. Direct access to ffmpeg was required.

Moreover, while the control flow might not be "straightforward", the author felt the risk was calculated and could be mitigated with several tricks:

3. On comments

Comments are code and code should be maintained. Function comments, notably, are crucial.

They should feature:

  • a brief description of the function goal
  • expected parameters and a description
    • + denotes a global parameter (declared and set outside the function scope)
    • ! denotes a mandatory parameter
    • ? denotes an optional parameter
    • * denotes an array parameter
    • ideally, a word in the following description indicates the expected parameter type (highlighted with '*')
  • interaction with global parameters
  • return codes and values
    • echoes is what the function echo on its STDOUT

4. bits_per_raw_sample 24

FFMPEG FLAC encoder cannot encore in 24 bits due to technical limitations. Thus, it is necessary to use a 32 bits bit depth, but the bits_per_raw_sample allows to specify it further.