Doc

README.md

@@ -96,7 +96,7 @@ and follow the above instructions for installing the other files needed.
 Note that this has less features compared to in_vgmstream and has no configuration.
 Since XMPlay supports Winamp plugins you may also use `in_vgmstream.dll` instead.
 
-Because the XMPlay MP3 decoder incorrectly tries to play some vgmstream exts,
+Because the XMPlay MP3 decoder incorrectly tries to play some vgmstream extensions,
 you need to manually fix it by going to **options > plugins > input > vgmstream**
 and in the "priority filetypes" put: `ahx,asf,awc,ckd,fsb,genh,msf,p3d,rak,scd,txth,xvag`
 
@@ -123,7 +123,7 @@ Usage: `vgmstream123 [options] INFILE ...`
 
 The program is meant to be a simple stand-alone player, supporting playback
 of vgmstream files through libao. Files compressed with gzip/bzip2/xz also
-work, as identified by a .gz/.bz2/.xz extension. The file will be decompressed
+work, as identified by a `.gz/.bz2/.xz` extension. The file will be decompressed
 to a temp dir using the respective utility program (which must be installed
 and accessible) and then loaded.
 
@@ -155,37 +155,37 @@ multiple .txtp (explained below) to select one of the subsongs (like `bgm.sxd#10
 
 You can use this python script to autogenerate one `.txtp` per subsong:
 https://github.com/losnoco/vgmstream/tree/master/cli/txtp_maker.py
-Put in the same dir as test.exe/vgmstream_cli, then to drag-and-drop files with subsongs
-to `txtp_maker.py`.
+Put in the same dir as test.exe/vgmstream_cli, then to drag-and-drop files with
+subsongs to `txtp_maker.py`.
 
 ### Renamed files
 A few extensions that vgmstream supports clash with common ones. Since players
 like foobar or Winamp don't react well to that, they may be renamed to make
 them playable through vgmstream.
-- .aac to .laac (tri-Ace games)
-- .ac3 to .lac3 (standard AC3)
-- .aif to .laif or .aiffl or .aifcl (standard Mac AIF, Asobo AIF, Ogg)
-- .aiff/aifc to .aiffl/aifcl (standard Mac AIF)
-- .asf to .lasf (EA games, Argonaut ASF)
-- .bin to .lbin (various)
-- .flac to .lflac (standard FLAC)
-- .mp2 to .lmp2 (standard MP2)
-- .mp3 to .lmp3 (standard MP3)
-- .mp4 to .lmp4 (standard M4A)
-- .mpc to .lmpc (standard MPC)
-- .ogg to .logg (standard OGG)
-- .opus to .lopus (standard OPUS or Switch OPUS)
-- .stm to .lstm (Rockstar STM)
-- .wav to .lwav (standard WAV)
-- .wma to .lwma (standard WMA)
-- .(any) to .vgmstream (FFmpeg formats or TXTH)
+- `.aac` to `.laac` (tri-Ace games)
+- `.ac3` to `.lac3` (standard AC3)
+- `.aif` to `.laif` (standard Mac AIF, Asobo AIF, Ogg)
+- `.aiff/aifc` to `.laiffl/laifc` (standard Mac AIF)
+- `.asf` to `.lasf` (EA games, Argonaut ASF)
+- `.bin` to `.lbin` (various)
+- `.flac` to `.lflac` (standard FLAC)
+- `.mp2` to `.lmp2` (standard MP2)
+- `.mp3` to `.lmp3` (standard MP3)
+- `.mp4` to `.lmp4` (standard M4A)
+- `.mpc` to `.lmpc` (standard MPC)
+- `.ogg` to `.logg` (standard OGG)
+- `.opus` to `.lopus` (standard OPUS or Switch OPUS)
+- `.stm` to `.lstm` (Rockstar STM)
+- `.wav` to `.lwav` (standard WAV)
+- `.wma` to `.lwma` (standard WMA)
+- `.(any)` to `.vgmstream` (FFmpeg formats or TXTH)
 
 Command line tools don't have this restriction and will accept the original
 filename.
 
 The main advantage to rename them is that vgmstream may use the file's
 internal loop info, or apply subtle fixes, but is also limited in some ways
-(like standard/player's tagging). .vgmstream is a catch-all extension that
+(like standard/player's tagging). `.vgmstream` is a catch-all extension that
 may work as a last resort to make a file playable.
 
 Some plugins have options that allow any extension (common or unknown) to be
@@ -209,54 +209,87 @@ vgmstream also supports audio from videos, but usually must be demuxed (extracte
 without modification) first, since vgmstream doesn't attempt to support them.
 
 The easiest way to do this is using VGMToolBox's "Video Demultiplexer" option
-for common game video formats (.bik, .vp6, .pss, .pam, .pmf, .usm, .xmv, etc).
+for common game video formats (`.bik`, `.vp6`, `.pss`, `.pam`, `.pmf`, `.usm`, `.xmv`, etc).
 
-For standard videos formats (.avi, .mp4, .webm, .m2v, .ogv, etc) not supported
-by VGMToolBox FFmpeg binary may work:
+For standard videos formats (`.avi`, `.mp4`, `.webm`, `.m2v`, `.ogv`, etc) not supported
+by VGMToolBox, FFmpeg binary may work:
 - `ffmpeg.exe -i (input file) -vn -acodec copy (output file)`
 Output extension may need to be adjusted to some appropriate audio file depending
-on the audio codec used. ffprobe.exe can list this codec, though the correct audio
-extension depends on the video itself (like .avi to .wav/mp2/mp3 or .ogv to .ogg).
+on the audio codec used. `ffprobe.exe` can list this codec, though the correct audio
+extension depends on the video itself (like `.avi` to `.wav/mp2/mp3` or `.ogv` to `.ogg`).
 
-Some games use custom video formats, demuxer scripts in .bms format may be found
+Some games use custom video formats, demuxer scripts in `.bms` format may be found
 on the internet.
 
 ### Companion files
-Some formats have companion files with external looping info, and should be
-left together.
-- .mus (playlist for .acm)
-- .pos (loop info for .wav, and sometimes .ogg)
-- .ogg.sli or .sli (loop info for .ogg)
-- .ogg.sfl (loop info for .ogg)
-- .vgmstream.pos (loop info for FFmpeg formats)
-  - also possible for certain extensions like .lflac.pos
+Some formats have companion files with external info, that should be left together:
+- `.mus`: playlist for `.acm`
+- `.ogg.sli` or `.sli`: loop info for `.ogg`
+- `.ogg.sfl` : loop info for `.ogg`
+- `.opus.sli`: loop info for `.opus`
+- `.pos`: loop info for .wav
+- `.vgmstream.pos`: loop info for FFmpeg formats
+- `.acb`: names for `.awb`
+- `.xsb`: names for `.xwb`
 
-Similarly some formats split header and/or data in separate files (.sgh+sgd,
-.wav.str+.wav, (file)_L.dsp+(file)_R.dsp, etc). vgmstream will also detect
-and use those as needed and must be together, even if only one of the two
-will be used to play.
+Similarly some formats split header+body data in separate files, examples:
+- `.abk`+`.ast`
+- `.bnm`+`.apm/wav`
+- `.ktsl2asbin`+`.ktsl2stbin`
+- `.mih`+`.mib`
+- `.mpf`+`.mus`
+- `.pk`+`.spk`
+- `.sb0`+`.sp0` (or other numbers instead of `0`)
+- `.sgh`+`.sgd`
+- `.snr`+`.sns`
+- `.spt`+`.spd`
+- `.sts`+`.int`
+- `.xwh`+`.xwb`
+- `.xps`+`dat`
+- `.wav.str`+`.wav`
+- `.wav`+`.dcs`
+- `.wbh`+`.wbd`
+Both are needed to play and must be together. The usual rule is you open the
+bigger file (body), save a few formats where the smaller file is opened instead
+for technical reasons (mainly some bank formats).
 
-Some formats may have companion files with different names which are hardcoded
-instead of being listed in the main file (e.g. .mpf+.mus). In these cases, you
-can use TXTM format to specify associated companion files. See below for more
-information.
+Generally companion files are named the same (`bgm.awb`+`bgm.acb`), or internally
+point to another file `sfx.sb0`+`STREAM.sb0`. A few formats may have different names
+which are hardcoded instead of being listed in the main file (e.g. `.mpf+.mus`).
+In these cases, you can use *TXTM* format to specify associated companion files.
+See *Artificial files* below for more information.
 
-.pos is a small file with 32 bit little endian values: loop start sample
-and  loop end sample. For FFmpeg formats (.vgmstream.pos) it may optionally
-have total samples after those.
+A special case of the above is "dual file stereo", where 2 similarly named mono
+files are fused together to make 1 stereo song.
+- `(file)_L.dsp`+`(file)_R.dsp`
+- `(file)-l.dsp`+`(file)-l.dsp`
+- `(file).L`+`(file).R`
+- `(file)_0.dsp`+`(file)_1.dsp`
+- `(file)_Left.dsp`+`(file)_Right.dsp`
+- `(file).v0`+`(file).v1`
+This is only allowed in a few formats (mainly `.dsp` and `.vag`). In those cases
+you can open either `L` or `R` and you'll get the same stereo song. If you rename
+one of the files the "pair" won't be found, and both will be played as mono.
+
+`.pos` is a small file with 32 bit little endian values: loop start sample and
+loop end sample. This is a real format, but is sometimes reused to force loops.
+If you want to force looping files consider using *TXTP* instead, as it's much
+simpler to make and cleaner: for example create a text file named `bgm01-loop.txtp`
+and inside write `bgm01.mp3 #I 10.0 90.0`. Open the `.txtp` to play the `.mp3`
+looping from 10 to 90 seconds.
 
 ### Decryption keys
 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)
-- .ahx: .ahxkey (derived 6 byte start/mult/add key)
-- .hca: .hcakey (8 byte decryption key, a 64-bit number)
+- `.adx`: `.adxkey` (keystring, 8 byte keycode, or 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)
   - May be followed by 2 byte AWB scramble key for newer HCA
-- .fsb: .fsbkey (decryption key, in hex)
-- .bnsf: .bnsfkey (decryption key, a string up to 24 chars)
+- `.fsb`: `.fsbkey` (decryption key, in hex)
+- `.bnsf`: `.bnsfkey` (decryption key, a string up to 24 chars)
 
-The key file can be ".(ext)key" (for the whole folder), or "(name).(ext)key"
+The key file can be `.(ext)key` (for the whole folder), or `(name).(ext)key"
 (for a single file). The format is made up to suit vgmstream.
 
 ### Artificial files
@@ -267,7 +300,7 @@ Those can be played using an artificial header with info vgmstream needs.
 
 **GENH**: a byte header placed right before the original data, modyfing it.
 The resulting file must be (name).genh. Contains static header data.
-Programs like VGMToolbox can help to create GENH.
+Programs like VGMToolbox can help to create *GENH*.
 
 **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
@@ -277,22 +310,21 @@ file, or static values.
 *TXTH* is recomended over *GENH* as it's far easier to create and has many
 more functions.
 
-
 For files that already play, sometimes they are used by the game in various
 complex and non-standard ways, like playing multiple small songs as a single
 one, or using some channels as a section of the song. For those cases we
-can use create a *TXTP* file.
+can create a *TXTP* file.
 
 **TXTP**: text files with player configuration, named `(name).txtp`. Text inside
 can contain a list of filenames to play as one (ex. `intro.vag(line)loop.vag`),
 list of separate channel files to join as a single multichannel file,
 subsong index (ex. `bgm.sxd#10`), per-file configurations like number of
-loops, remove unneeded channels, and many other features.
+loops, remove unneeded channels, make looping files, and many other features.
 
 **TXTM**: text file named `.txtm` for formats with companion files. It lists
 name combos determining which companion files to load for each main file.
 It is useful for formats where name combos are hardcoded so vgmstream doesn't
-know which companion file(-s) to load if its name doesn't match the main file.
+know which companion file(s) to load if its name doesn't match the main file.
 Note that companion file order is usually important.
 
 Usage example:
@@ -301,6 +333,10 @@ Usage example:
 entrance.mpf:entrance.mus,entrance_o.mus
 willow.mpf:willow.mus,willow_o.mus
 ```
+```
+# Metal Gear Solid: Snake Eater 3D (3DS) names for .awb
+bgm_2_streamfiles.awb: bgm_2.acb
+```
 
 Creation of those files is meant for advanced users, docs can be found in
 vgmstream source.
@@ -313,10 +349,10 @@ really opening it (should show "VGMSTREAM" somewhere in the file info), and
 try to remove a few other plugins.
 
 foobar's FFmpeg plugin and foo_adpcm are known to cause issues, but in
-recent versions (1.4.x) you can configure plugin priority.
+modern versions (+1.4.x) you can configure plugin priority.
 
 In Audacious, vgmstream is set with slightly higher priority than FFmpeg,
-since it steals many formats that you normally want to loop (like .adx).
+since it steals many formats that you normally want to loop (like `.adx`).
 However other plugins may set themselves higher, stealing formats instead.
 If current Audacious version doesn't let to change plugin priority you may
 need to disable some plugins (requires restart) or set priority on compile
@@ -335,6 +371,7 @@ since it can't guess how the file should be properly adjusted).
 
 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 tweak how files is downmixed.
 
 
 ## Tagging
@@ -400,8 +437,8 @@ enabled in preferences):
 ```
 
 ### TXTP matching
-To ease *TXTP* config, tags with plain files will match .txtp with config, and tags
-with .txtp config also match plain files:
+To ease *TXTP* config, tags with plain files will match `.txtp` with config, and tags
+with `.txtp` config also match plain files:
 **!tags.m3u**
 ```
 # @TITLE    Title1
@@ -441,7 +478,7 @@ BGM01.adx #I 1.0 90.0 .txtp
 
 ### Issues
 If your player isn't picking tags make sure vgmstream is detecting the song
-(as other plugins can steal its extensions, see above), .m3u is properly
+(as other plugins can steal its extensions, see above), `.m3u` is properly
 named and that filenames inside match the song filename. For Winamp you need
 to make sure *options > titles > advanced title formatting* checkbox is set and
 the format defined.
@@ -453,11 +490,11 @@ When tags change behavior varies depending on player:
 - *Audacious*: files need to be readded to the playlist
 
 Currently there is no tool to aid in the creation of these tags, but you can create
-a base .m3u and edit as a text file.
+a base `.m3u` and edit as a text file.
 
 vgmstream's "m3u tagging" is meant to be simple to make and share (just a text
 file), easier to support in multiple players (rather than needing a custom plugin),
-allow OST-like ordering but also combinable with other .m3u, and be flexible enough
+allow OST-like ordering but also combinable with other `.m3u`, and be flexible enough
 to have commands. If you are not satisfied with vgmstream's tagging format,
 foobar2000 has other plugins (with write support) that may be of use:
 - m-TAGS: http://www.m-tags.org/
@@ -465,14 +502,14 @@ foobar2000 has other plugins (with write support) that may be of use:
 
 
 ## Virtual TXTP files
-Some of vgmstream's plugins allow you to use virtual .txtp files, that combined
+Some of vgmstream's plugins allow you to use virtual `.txtp` files, that combined
 with playlists let you make quick song configs.
 
 Normally you can create a physical .txtp file that points to another file with
-config, and .txtp have a "mini-txtp" mode that configures files with only the
+config, and `.txtp` have a "mini-txtp" mode that configures files with only the
 filename.
 
-Instead of manually creating .txtp files you can put non-existing virtual .txtp
+Instead of manually creating `.txtp` files you can put non-existing virtual `.txtp`
 in a `.m3u` playlist:
 ```
 # playlist that opens subsongs directly without having to create .txtp
@@ -502,14 +539,18 @@ You can also use it in CLI for quick access to some txtp-exclusive functions:
 test.exe -o btl_koopa1_44k_lp.wav "btl_koopa1_44k_lp.brstm  #h22050.txtp"
 ```
 
+Support for this feature is limited by player itself, as foobar and Winamp allow
+non-existant files referenced in a `.m3u`, while other players may filter them
+first.
+
 
 ## Supported codec types
 Quick list of codecs vgmstream supports, including many obscure ones that
 are used in few games.
 
 - PCM 16-bit
-- PCM 8-bit (signed/unsigned)
-- PCM 4-bit (signed/unsigned)
+- PCM 8-bit (signed, unsigned)
+- PCM 4-bit (signed, unsigned)
 - PCM 32-bit float
 - u-Law/a-LAW
 - CRI ADX (standard, fixed, exponential, encrypted)