doc

doc/BUILD.md

@@ -553,7 +553,7 @@ To compile we'll use autotools with GCC preprocessor renaming:
   # creates Makefiles with Automake
   sh.exe ./configure --build=mingw32 --prefix=/c/celt0.6.1/bin/  --exec-prefix=/c/celt-0.6.1/bin/
 
-  # LDFLAGS are needed to create the .dll (Automake whinning)
+  # LDFLAGS are needed to create the .dll (Automake whining)
   # CFLAGS rename a few CELT functions (we don't import the rest so they won't clash)
   mingw32-make.exe clean
   mingw32-make.exe LDFLAGS="-no-undefined" AM_CFLAGS="-Dcelt_decode=celt_0061_decode -Dcelt_decoder_create=celt_0061_decoder_create -Dcelt_decoder_destroy=celt_0061_decoder_destroy -Dcelt_mode_create=celt_0061_mode_create -Dcelt_mode_destroy=celt_0061_mode_destroy -Dcelt_mode_info=celt_0061_mode_info"
@@ -563,7 +563,7 @@ To compile we'll use autotools with GCC preprocessor renaming:
   # creates Makefiles with Automake
   sh.exe ./configure --build=mingw32 --prefix=/c/celt-0.11.0/bin/  --exec-prefix=/c/celt-0.11.0/bin/
 
-  # LDFLAGS are needed to create the .dll (Automake whinning)
+  # LDFLAGS are needed to create the .dll (Automake whining)
   # CFLAGS rename a few CELT functions (notice one is different vs 0.6.1), CUSTOM_MODES is also a must.
   mingw32-make.exe clean
   mingw32-make.exe LDFLAGS="-no-undefined" AM_CFLAGS="-DCUSTOM_MODES=1 -Dcelt_decode=celt_0110_decode -Dcelt_decoder_create_custom=celt_0110_decoder_create_custom -Dcelt_decoder_destroy=celt_0110_decoder_destroy -Dcelt_mode_create=celt_0110_mode_create -Dcelt_mode_destroy=celt_0110_mode_destroy -Dcelt_mode_info=celt_0110_mode_info"
@@ -572,10 +572,12 @@ To compile we'll use autotools with GCC preprocessor renaming:
 - you need to create a .def file for those DLL with the renamed simbol names above
 - finally the includes. libcelt gives "celt.h" "celt_types.h" "celt_header.h", but since we renamed a few functions we have a simpler custom .h with minimal renamed symbols.
 
-For **Linux**, an option is using AUR's scripts (https://aur.archlinux.org/packages/vgmstream-git/) that similarly patch celt libs in PKGBUILD.
+For **Linux**, you can use CMake that similarly patch celt libs automatically.
 
 You can also get them from the official git (https://gitlab.xiph.org/xiph/celt) call `./autogen.sh` first, then pass call configure/make with renames (see `./make-build.sh`).
 
+Instead of passing `-DCUSTOM_MODES=1` to `make` you can pass `--enable-custom-codes` to *./configure*. There is also `--disable-oggtests`, `--disable-static/shared` and typical config. Note that if *./configure* finds Ogg in your system it'll try to build encoder/decoder test `tools` (that depend on libogg). There is no official way disable that or compile `libcelt` only, but you can force it by calling `make SUBDIRS=libcelt DIST_SUBDIRS=libcelt`, in case you have dependency issues.
+
 ### libspeex
 Adds support for Speex (inside custom containers), used in a few *EA* formats (`.sns`, `.sps`) for voices.
 - Source: http://downloads.us.xiph.org/releases/speex/speex-1.2.0.tar.gz

doc/USAGE.md

@@ -338,10 +338,11 @@ Regular formats without companion files should work fine in upper/lowercase. For
 Certain formats have encrypted data, and need a key to decrypt. vgmstream
 will try to find the correct key from a list, but it can be provided by
 a companion file:
-- `.adx`: `.adxkey` (keystring, 8 byte keycode, or derived 6 byte start/mult/add key)
+- `.adx`: `.adxkey` (keystring, 8-byte keycode, or derived 6 byte start/mult/add key)
-- `.ahx`: `.ahxkey` (derived 6 byte start/mult/add key)
+- `.ahx`: `.ahxkey` (derived 6-byte start/mult/add key)
-- `.hca`: `.hcakey` (8 byte decryption key, a 64-bit number)
+- `.hca`: `.hcakey` (8-byte decryption key, a 64-bit number)
-  - May be followed by 2 byte AWB scramble key for newer HCA
+  - `.awb`/`.acb` also may use `.hcakey`, and will combine with an internal AWB subkey
+  - May set a 8-byte key followed a 2-byte AWB subkey for newer HCA
 - `.fsb`: `.fsbkey` (decryption key in hex, usually between 8-32 bytes) 
 - `.bnsf`: `.bnsfkey` (decryption key, a string up to 24 chars)
 
@@ -360,22 +361,12 @@ needs.
 Creation of these files is meant for advanced users, full docs can be found in
 vgmstream source.
 
-#### GENH
-A byte header placed right before the original data, modifying it.
-The resulting file must be `(name).genh`. Contains static header data.
-
-Programs like VGMToolbox can help to create *GENH*, but consider using *TXTH*
-instead, *GENH* is mostly deprecated.
-
 #### TXTH
 A text header placed in an external file. The TXTH must be named
 `.txth` or `.(ext).txth` (for the whole folder), or `(name.ext).txth` (for a
 single file). Contains dynamic text commands to read data from the original
 file, or static values. This allows vgmstream to play unsupported formats.
 
-*TXTH* is recommended over *GENH* as it's far easier to create and has many
-more functions, plus doesn't modify original data.
-
 Usage example (used when opening an unknown file named `bgm_01.pcm`):
 
 **.pcm.txth**
@@ -464,6 +455,16 @@ effect_dlc2.awb: effect.acb
 effect_dlc3.awb: effect.acb
 ```
 
+#### GENH
+A byte header placed right before the original data, modifying it.
+The resulting file must be `(name).genh`. Contains static header data.
+
+Programs like VGMToolbox can help to create *GENH*, but consider using *TXTH*
+instead, *GENH* is mostly deprecated. *TXTH* is recommended over *GENH* as
+it's far easier to create and has many more functions, plus doesn't modify
+original data.
+
+
 ### Plugin conflicts
 Since vgmstream supports a huge amount of formats it's possibly that some of
 them are also supported in other plugins, and this sometimes causes conflicts.
@@ -496,7 +497,8 @@ adjusted. Most likely it will sound a bit quieter than usual.
 
 You can also choose which channels to play using *TXTP*. For example, create
 a file named `song.adx#C1,2.txtp` to play only channels 1 and 2 from `song.adx`.
-*TXTP* also has command to set how files are downmixed.
+*TXTP* also has command to set how files are downmixed, like `song.adx #@downmix.txtp`
+for standard 5.1/4.0/etc audio to stereo, or manual (per-channel) mixing.
 
 ### Average bitrate
 Note that vgmstream shows the "file bitrate" (counts all data) as opposed to
@@ -517,6 +519,35 @@ There are many factors in play like encoder, type of codec, sample rate and so o
 A higher bitrate `.wav` can sound worse than a lower `.ogg` (like mono 22050hz `.wav`
 vs stereo 48000hz `.ogg`).
 
+### Containers
+Some formats are *audio containers* of other common audio formats. For example
+`.acb`/`.awb` may contain standard `.hca` inside. Rather than extracting the
+internal "files", it's recommended that you keep data unmodified for preservation
+purposes. Sometimes containers have useful data (like loop info or names), that
+you may be unknowingly throwing away if you extract internal files.
+
+It's a good practice (and simpler) to just let containers be and play them
+directly with vgmstream. Newer `.acb`/`.awb` have extra data needed to decrypt
+the `.hca`, so if you are already used to those containers you don't need to
+worry about extracted `.hca` not working later. Plus you can use TXTH's "subfile"
+function to make unsupported containers playable:
+```
+# Simple container with an Ogg inside. Maybe values 0x00..0x10 could contain
+# loops or other useful info, that other users are able to figure out:
+subfile_extension = ogg
+subfile_offset = 0x10
+```
+With unmodified data, you can always extract the internal files later if you
+change your mind, but you can't get the (potentially useful) container data back
+once extracted.
+
+However, if your file is a *generic container* (like a `.zip`, that could hold
+graphics or audio) you may safely extract the internal files without worry.
+
+Note that some formats are *audio banks* rather than *containers* (like `.fsb`),
+in that info for playing the audio is part of the bank header, and extracting
+internal files as-is isn't really possible.
+
 
 ## Logged errors and unplayable supported files
 Some formats should normally play, but somehow don't. In those cases plugins