upload tools

tools/vgmstream/COPYING

@@ -0,0 +1,22 @@
+Copyright (c) 2008-2019 Adam Gashlin, Fastelbja, Ronny Elfert, bnnm,
+                        Christopher Snowhill, NicknineTheEagle, bxaimc,
+                        Thealexbarney, CyberBotX, et al
+
+Portions Copyright (c) 2004-2008, Marko Kreen
+Portions Copyright 2001-2007  jagarl / Kazunori Ueno <jagarl@creator.club.ne.jp>
+Portions Copyright (c) 1998, Justin Frankel/Nullsoft Inc.
+Portions Copyright (C) 2006 Nullsoft, Inc.
+Portions Copyright (c) 2005-2007 Paul Hsieh
+Portions Public Domain originating with Sun Microsystems
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

tools/vgmstream/README.md

@@ -0,0 +1,104 @@
+# vgmstream
+This is vgmstream, a library for playing streamed (prerecorded) video game audio.
+
+Some of vgmstream's features:
+- [Hundreds of video game music formats and codecs](doc/FORMATS.md), from typical game engine files
+  to obscure single-game codecs, aiming for high accuracy and compatibility.
+- Support for looped BGM, using file's internal metadata for smooth transitions, with accurate
+  sample counts.
+- [Subsongs](doc/USAGE.md#subsongs), playing a format's multiple internal songs separately.
+- Many types of companion files (data split into multiple files) and custom containers.
+- Encryption keys, internal stream names, and many other unusual cases found in game audio.
+- [TXTH](doc/TXTH.md) function, to add external support for extra formats, including raw audio in
+  many forms.
+- [TXTP](doc/TXTP.md) function, for real-time and per-file config, like forced looping, removing
+  channels, playing certain subsong, or fusing multiple files into a single one.
+- Simple [external tagging](doc/USAGE.md#tagging) via .m3u files.
+- [Plugins](#getting-vgmstream) are available for various media player software and operating systems.
+
+The main development repository: https://github.com/vgmstream/vgmstream/
+
+Automated builds with the latest changes: https://vgmstream.org
+(https://github.com/vgmstream/vgmstream-releases/releases/tag/nightly)
+
+Common releases: https://github.com/vgmstream/vgmstream/releases
+
+Help can be found here: https://www.hcs64.com/
+
+More documentation: https://github.com/vgmstream/vgmstream/tree/master/doc
+
+## Getting vgmstream
+There are multiple end-user components:
+- [vgmstream-cli](doc/USAGE.md#testexevgmstream-cli-command-line-decoder): A command-line decoder.
+- [in_vgmstream](doc/USAGE.md#in_vgmstream-winamp-plugin): A Winamp plugin.
+- [foo_input_vgmstream](doc/USAGE.md#foo_input_vgmstream-foobar2000-plugin): A foobar2000 component.
+- [xmp-vgmstream](doc/USAGE.md#xmp-vgmstream-xmplay-plugin): An XMPlay plugin.
+- [vgmstream.so](doc/USAGE.md#audacious-plugin): An Audacious plugin.
+- [vgmstream123](doc/USAGE.md#vgmstream123-command-line-player): A command-line player.
+
+The main library (plain *vgmstream*) is the code that handles the internal conversion, while the
+above components are what you use to get sound.
+
+If you want to convert game audio to `.wav`, try getting *vgmstream-cli* (see below) then
+drag-and-drop one or more files to the executable (support may vary per O.S. or distro).
+This should create `(file.extension).wav`, if the format is supported. More user-friendly
+would be installing a player like *foobar2000* (for Windows) or *Audacious* (for Linux)
+and the vgmstream plugin. Then you can directly listen your files and set options like infinite
+looping, or convert to `.wav` with the player's options (also easier if your file has multiple
+"subsongs").
+
+See [components](doc/USAGE.md#components) in the *usage guide* for full install instructions and
+explanations. The aim is feature parity, but there are a few differences between them due to
+missing parts on vgmstream's side or lack of support in the player.
+
+Note that vgmstream cannot *encode* (convert from `.wav` to a video game format), it only *decodes*
+(plays game audio).
+
+
+### Windows
+Get the latest prebuilt binaries (CLI/plugins/etc) on our website:
+- https://vgmstream.org
+
+Or the less frequent "official" releases on GitHub:
+- https://github.com/vgmstream/vgmstream/releases
+
+The foobar2000 component is also available on https://www.foobar2000.org based on current
+release.
+
+If the above links fail, you may also try the alternative versions built by
+[bnnm](https://github.com/bnnm):
+- https://github.com/bnnm/vgmstream-builds/raw/master/bin/vgmstream-latest-test-u.zip
+
+You may compile from source as well, see the [build guide](doc/BUILD.md).
+
+### Linux
+A prebuilt CLI binary is available. It's statically linked and should work on systems running
+Linux kernel v3.2 and above:
+- https://vgmstream.org
+- https://github.com/vgmstream/vgmstream/releases
+
+Building from source will also give you *vgmstream.so* (Audacious plugin), and *vgmstream123*
+(command-line player).
+
+When building, many extra components have to be installed or compiled separately, which the
+[build guide](doc/BUILD.md) describes in detail. For a quick build on Debian and Ubuntu-style
+distributions run `./make-build-cmake.sh`. The script will need to install various dependencies,
+so you may prefer to copy commands and run them manually.
+
+### macOS
+A prebuilt CLI binary is available as well:
+- https://vgmstream.org
+- https://github.com/vgmstream/vgmstream/releases
+
+Otherwise follow the [build guide](doc/BUILD.md).
+
+
+## More info
+- [Usage guide](doc/USAGE.md)
+- [List of supported audio formats](doc/FORMATS.md)
+- [Build guide](doc/BUILD.md)
+- [TXTH file format](doc/TXTH.md)
+- [TXTP file format](doc/TXTP.md)
+
+
+Enjoy! *hcs*

tools/vgmstream/USAGE.md

@@ -0,0 +1,911 @@
+# Usage
+
+## Needed extra files
+On Windows support for some codecs (Ogg Vorbis, MPEG audio, etc.) is done with external
+libraries, so you will need to put certain DLL files together.
+
+In the case of components like foobar2000 they are all bundled for convenience,
+while other components include them but must be installed manually. You can also
+get them here: https://github.com/vgmstream/vgmstream/tree/master/ext_libs
+or compile them manually, even (see tech docs).
+
+Put the following files somewhere Windows can find them:
+- `libvorbis.dll`
+- `libmpg123-0.dll`
+- `libg719_decode.dll`
+- `avcodec-vgmstream-59.dll`
+- `avformat-vgmstream-59.dll`
+- `avutil-vgmstream-57.dll`
+- `swresample-vgmstream-4.dll`
+- `libatrac9.dll`
+- `libcelt-0061.dll`
+- `libcelt-0110.dll`
+- `libspeex-1.dll`
+
+For command line (`vgmstream-cli.exe`) and XMPlay this means in the directory with the main
+`.exe`, or possibly a directory in the PATH variable.
+
+For Winamp, the above `.dll` also go near main `winamp.exe`, but note that `in_vgmstream.dll`
+plugin itself goes in `Plugins`.
+
+On other OSs like Linux/Mac, libs need to be installed before compiling, then should be used
+automatically, though not all may enabled at the moment due to build scripts issues.
+
+
+## Components
+
+### vgmstream-cli (command line decoder)
+*Windows*: unzip `vgmstream-cli` and follow the above instructions for installing needed extra files.
+This tool was called `test.exe` before for historical reasons (rename back if needed).
+
+*Others*: build instructions can be found in the [BUILD.md](BUILD.md) document (can be compiled
+with CMake/Make/autotools).
+
+Converts playable files to `.wav`. Typical usage would be:
+- `vgmstream-cli -o happy.wav happy.adx` to decode `happy.adx` to `happy.wav`.
+
+If command-line isn't your thing you can simply drag and drop one or multiple
+files to the executable to decode them as `(filename.ext).wav`.
+
+There are multiple options that alter how the file is converted, for example:
+- `vgmstream-cli -m file.adx`: print info but don't decode
+- `vgmstream-cli -i -o file_noloop.wav file.hca`: convert without looping
+- `vgmstream-cli -s 2 -F file.fsb`: write 2nd subsong + ending after 2.0 loops
+- `vgmstream-cli -l 3.0 -f 5.0 -d 3.0 file.wem`: 3 loops, 3s delay, 5s fade
+- `vgmstream-cli -o bgm_?f.wav file1.adx file2.adx`: convert multiple files to `bgm_(name).wav`
+
+Available commands are printed when run with no flags. Note that you can also
+achieve similar results for other plugins using TXTP, described later.
+
+Output filename in `-o` may use wildcards:
+- `?s`: sets current subsong (or 0 if format doesn't have subsongs)
+- `?0Ns`: same, but left pads subsong with up to `N` zeroes
+- `?n`: internal stream name, or input filename if format doesn't have name
+- `?f`: input filename
+
+For example `vgmstream-cli -s 2 -o ?04s_?n.wav file.fsb` could generate `0002_song1.wav`.
+Default output filename is `?f.wav`, or `?f#?s.wav` if you set subsongs (`-s/-S`).
+
+
+### in_vgmstream (Winamp plugin)
+*Windows*: drop the `in_vgmstream.dll` in your Winamp Plugins directory,
+and follow the above instructions for installing needed extra files.
+
+*Others*: may be possible to use through *Wine*.
+
+Once installed, supported files should be playable. There is a simple config
+menu to tweak some options too. If the *Preferences... > Plug-ins > Input* shows
+vgmstream as *"NOT LOADED"* that means extra DLL files aren't in the correct
+place.
+
+#### Plugin priority
+An (uncommon) issue is clashing extensions. When opening a file, Winamp first
+asks all plugins if they support the file. Here vgmstream accepts files it can
+play and rejects anything it can't, but if no plugin "claims" the file (and most
+don't), Winamp will just pass it to the *first* `.dll` in the plugin folder that
+reports the extension. Since vgmstream supports tons of extensions sometimes it
+may receive files it can't play (even after rejecting them before). This oddness
+can be solved by renaming the plugins' `.dll` so vgmstream goes *last*.
+
+For example, vgmstream ignores sequenced `.vgm` but supports streamed `.vgm` (another
+format). If your *in_vgm* plugin version doesn't "claim" sequenced `.vgm` Winamp
+may send it to vgmstream by mistake (so won't be playable), depending on how it's
+named. Here vgmstream has higher priority and fail:
+```
+in_vgmstream.dll
+in_vgmW.dll
+```
+And here has lower and will be playable:
+```
+in_vgm.dll
+in_vgmstream.dll
+```
+
+Note the above is also affected by vgmstream's options *Enable common exts* (vgmstream
+will accept and play common files like `.wav` or `.ogg`), and *Enable unknown exts* (will
+try to play files outside the known extension list, which is often possible through *TXTH*).
+
+
+### foo_input_vgmstream (foobar2000 plugin)
+*Windows*: every file should be installed automatically when opening the `.fb2k-component`
+bundle.
+
+*Others*: may be possible to use through *Wine*.
+
+Note that vgmstream currently requires at least foobar v1.5 to run.
+
+#### Plugin priority
+If multiple plugins supports the same format, which plugin is used depends on config.
+You can change plugin's priority in **options > Playback > Decoding**. Due to the
+huge amount of supported formats, you may want to set it low enough.
+
+Note the above is also affected by vgmstream's options *Enable common exts* (vgmstream
+will accept and play common files like `.wav` or `.ogg`), and *Enable unknown exts* (will
+try to play files outside the known extension list, which is often possible through *TXTH*).
+
+#### Default title
+By default *vgmstream* auto-generates a `title` tag depending on subsongs, stream name
+and other details. You can change this by setting *"override title"* in the options,
+that uses foobar's default (filename without extension) and tweating the display format
+in *Preferences > Display > Default User Interface* (may need to add some conditionals
+to handle files with/out subsongs). *vgmstream* automatically exports these tags:
+- `STREAM_INDEX`: current subsong, if file has subsongs, starts from 1
+- `STREAM_COUNT`: total subsongs, if file has subsongs
+- `STREAM_NAME`: internal name, that also exists in some formats without subsongs
+For example: `[%artist% - ]%title% [%stream_index%][/ %stream_name%]` 
+
+You can also set an unique *Destination* pattern when converting to .wav (even without)
+setting *override title*). For example `[$num(%stream_index%,2)] %filename%[-%stream_name%]` 
+may create a name like `02 BGM-EVENT_SAD`.
+
+#### Playlist issues
+A known quirk is that when loop options or tags change, playlist time/info won't
+update automatically. You need to manually refresh it by selecting songs and doing
+**shift + right click > Tagging > Reload info from file(s)**.
+
+
+### xmp-vgmstream (XMPlay plugin)
+*Windows*: drop the `xmp-vgmstream.dll` in your XMPlay plugins directory,
+and follow the above instructions for installing the other files needed.
+
+*Others*: may be possible to use through *Wine*.
+
+Note that this has less features compared to *in_vgmstream* and has no config.
+Since XMPlay supports Winamp plugins you may also use `in_vgmstream.dll` instead.
+
+#### Plugin priority
+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,lwav,msf,p3d,rak,scd,txth,xvag`
+(or any other similar case).
+
+#### Missing subsongs
+XMPlay cannot support vgmstream's type of mixed subsongs due to player limitations
+(with neither *xmp-vgmstream* nor *in_vgmstream* plugins). You can make one *TXTP*
+per subsong to play them instead (explained below).
+
+
+### Audacious plugin
+*Windows*: not possible at the moment.
+
+*Others*: needs to be manually built. Instructions can be found in [BUILD.md](BUILD.md)
+document in vgmstream's source code (can be done with CMake or autotools).
+
+#### Plugin priority
+vgmstream sets its priority on compile time, low enough for most other plugins to
+go first (but not all). Can be changed with `AUDACIOUS_VGMSTREAM_PRIORITY`.
+
+
+### vgmstream123 (command line player)
+*Windows/Linux*: needs to be manually built. Instructions can be found in the
+*[BUILD.md](BUILD.md)* document. On Windows it needs `libao.dll` and appropriate includes.
+
+Usage: `vgmstream123 [options] INFILE ...`
+
+The program is meant to be a simple stand-alone player, supporting playback of
+vgmstream files through libao. Most options should be similar to CLI's
+(`-m`, `-i`, `-s N` and so on, though not fully equivalent), use `-h` for full info.
+
+#### Extra features
+On Linux, files compressed with gzip/bzip2/xz also 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.
+
+It also supports playlists, and will recognize a special extended-M3U tag
+specific to vgmstream of the following form:
+```
+#EXT-X-VGMSTREAM:LOOPCOUNT=2,FADETIME=10.0,FADEDELAY=0.0,STREAMINDEX=0
+```
+(Any subset of these four parameters may appear in the line, in any order)
+
+When this "magic comment" appears in the playlist before a vgmstream-compatible
+file, the given parameters will be applied to the playback of said file. This makes
+it feasible to play vgmstream files directly instead of needing to make "arranged"
+WAV/MP3 conversions ahead of time.
+
+The tag syntax follows the conventions established in Apple's HTTP Live Streaming
+standard, whose docs discuss extending M3U with arbitrary tags.
+
+
+## Special cases
+vgmstream aims to support most audio formats as-is, but some files require extra
+handling.
+
+### Subsongs
+Certain container formats have multiple audio files, usually called "subsongs", often
+not meant to be extracted (no simple separation from container).
+
+By default vgmstream plays first subsong and reports total subsongs, if the format
+is able to contain them. Easiest to use would be the *foobar/winamp/Audacious*
+plugins, that are able to "unpack" those subsongs automatically into the playlist.
+
+With CLI tools, you can select a subsong using the `-s` flag followed by a number,
+for example: `vgmstream-cli -s 5 file.bank` or `vgmstream123 -s 5 file.bank`.
+
+Using *vgmstream-cli* you can convert multiple subsongs at once using the `-S` flag.
+**WARNING, MAY TAKE A LOT OF SPACE!** Some files have been observed to contain +20000
+subsongs, so don't use this lightly. Remember to set an output name (`-o`) with subsong
+wildcards (or leave it alone for the defaults).
+- `vgmstream-cli -s 1 -S 100 file.bank`: writes from subsong 1 to subsong 100
+- `vgmstream-cli -s 101 -S 0 file.bank`: writes from subsong 101 to max subsong (automatically changes 0 to max)
+- `vgmstream-cli -S 0 file.bank`: writes from subsong 1 to max subsong
+- `vgmstream-cli -s 1 -S 5 -o bgm.wav file.bank`: writes 5 subsongs, but all overwrite the same file = wrong.
+- `vgmstream-cli -s 1 -S 5 -o bgm_?02s.wav file.bank`: writes 5 subsongs, each named differently = correct.
+
+For other players without support, or to play only a few choice subsongs, you
+can create multiple `.txtp` (explained later) to select one, like `bgm.sxd#10.txtp`
+(plays subsong 10 in `bgm.sxd`).
+
+You can use this python script to autogenerate one `.txtp` per subsong:
+https://github.com/vgmstream/vgmstream/tree/master/cli/tools/txtp_maker.py
+Put in the same dir as *vgmstream-cli*, then to drag-and-drop files with
+subsongs to `txtp_maker.py` (it has CLI options to control output too).
+
+### Common and unknown extensions
+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 these
+"designated fake extensions" to make them playable through vgmstream.
+- `.aac` to `.laac` (tri-Ace games)
+- `.ac3` to `.lac3` (standard AC3)
+- `.aif` to `.laif` (standard Mac AIF, Asobo AIF, Ogg)
+- `.aiff/aifc` to `.laiff/laifc` (standard Mac AIF)
+- `.asf` to `.lasf` (EA games, Argonaut ASF)
+- `.bin` to `.lbin` (various formats)
+- `.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, various formats)
+- `.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 of renaming here is that vgmstream may use the file's internal
+loop info, or apply subtle fixes, but is also limited in some ways (like ignoring
+standard tags). `.vgmstream` is a catch-all extension that may work as a last resort
+to make a file playable.
+
+Some plugins have options that allow "*common extensions*" to be played, making any
+renaming unnecessary. You may need to adjust plugin priority in player's options
+first. Note that vgmstream also accepts certain extension-less files as-is too.
+
+Similarly, vgmstream has a curated list of known extensions, that plugins may take
+into account and ignore unknowns. Through *TXTH* you can make unknown files playable,
+but you also need to either rename or set plugin options to allow "*unknown extensions*"
+(or, preferably, report this new extension so it can be added to the known list).
+
+It's also possible to make a .txtp file that opens files with those common/unknown
+extensions as a way to force them into vgmstream without renaming.
+
+#### Related issues
+Also be aware that other plugins (not vgmstream) can tell the player they handle
+some extension, then not actually play it. This makes the file unplayable as
+vgmstream doesn't even get the chance to parse it, so you may need to disable
+the offending plugin or rename the file to the fake extension shown above (for
+example this may happen with `.asf` in foobar2000/Winamp, may be fixed in newer
+versions).
+
+When extracting from a bigfile, sometimes internal files don't have a proper
+extension. Those should be renamed to its correct one when possible, as the
+extractor program may guess wrong (like `.wav` instead of `.at3` or `.wem`).
+If there is no known extension, usually the header id/magic string may be used instead.
+
+#### Windows 10 folder bugs
+Windows 10's *Web Media Extensions* is a pre-installed package seems to read metadata
+from files like `.ogg`, `.opus`, `.flac` and so on when opening a folder. However
+it tends to noticeably slow down opening folders, also seems to crash and leave files
+unusable when reading unsupported formats like Switch Opus (rather than Ogg Opus).
+
+Renaming extensions should prevent those issues, or just uninstall those *Web
+Media Extension* for better experience anyway.
+
+#### Fallout SFX .ACM
+Due to technical limitations, to play Fallout 1/2 SFX you need to rename them from
+`.acm` to `.wavc` (forces mono).
+
+### Demuxed videos
+vgmstream also supports audio from videos, but usually must be demuxed (extracted
+without modification) first, since vgmstream doesn't attempt to support most of them
+(it does support a few video formats as-is though).
+
+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 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`).
+
+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 info, that should be left together:
+- `.mus`: playlist with `.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
+- `.acb`: names for `.awb`
+- `.xsb`: names for `.xwb`
+
+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 (header) file is opened
+instead for technical reasons (mainly some bank formats).
+
+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 header 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.
+
+#### Dual stereo
+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`
+
+vgmstream automatically detects these pairs and makes a stereo song from `L` + `R`.
+You can open either `L` or `R` and you'll get the same stereo. If you rename one
+of the files the "pair" won't be found, and both will be played as mono. This
+is only done for a few choice formats (mainly `.dsp` and `.vag`) that commonly
+split audio like that, though.
+
+#### OS case sensitiveness
+When using OS with case sensitive filesystem (mainly Linux), a known issue with
+companion files is that vgmstream generally tries to find them using lowercase
+extension.
+
+This means that if the developer used uppercase instead (e.g. `bgm.ABK`+`bgm.AST`)
+loading will fail. It's technically complex to fix this, so for the time being
+the only option is renaming the companion extension to lowercase.
+
+A particularly nasty variation of that is that some formats load files by full
+name (e.g. `STREAM.SS0`), but sometimes the actual filename is in other case
+(`Stream.ss0`), and some files could even point to that with yet another case.
+You could try adding *symlinks* in various upper/lower/mixed cases to handle this,
+though only a few formats do this, mainly *Ubisoft* banks.
+
+Regular formats without companion files should work fine in upper/lowercase. For
+`.(ext).txth` files make sure `(ext)` matches case too.
+
+### 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` (keystring, or derived 6-byte start/mult/add key)
+- `.hca`: `.hcakey` (8-byte decryption key, a 64-bit number)
+  - `.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)
+
+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
+In some cases a file only has raw data, while important header info (codec type,
+sample rate, channels, etc) is stored in the .exe or other hard to locate places.
+Or maybe the file plays normally, but has many layers at once that are silenced
+dynamically during gameplay, or looping metadata is stored externally.
+
+Cases like those can be supported using an artificial files with info vgmstream
+needs.
+
+Creation of these files is meant for advanced users, full docs can be found in
+vgmstream source.
+
+#### TXTH
+Text files describing a format's header, to make unsupported files playable
+(helps vgmstream understand the file you are trying to open).
+
+Must be named `.txth` or `.(ext).txth` (used for the whole folder), or 
+`(name.ext).txth` (used for a single file). `.txth` are indirectly used when
+a `(file.ext)` is opened but vgmstream can't play it by default.
+
+`.txth` contains static values, or dynamic text commands to read data from the
+original file, serving as a fake header of sorts.
+
+Usage example (used when opening an unknown file named `bgm_01.pcm`):
+
+**.pcm.txth**
+```
+codec = PCM16LE         #standard PCM wave data
+channels = @0x04        #read in the file, at offset 4
+sample_rate = 48000     #hardcoded
+start_offset = 0x10     #first 0x10 bytes are the header
+num_samples = data_size #auto
+```
+
+#### TXTP
+Text files that apply playback parameters, to customize how other files are
+played.
+
+Must be named `(any name).txtp` and opened directly. Useful when games play songs
+in various non-standard ways, so we can tell vgmstream to handle files differently.
+
+`.txtp` can do multiple things (can be combined, too):
+- join a playlist of files (for separate intro + loop songs)
+- play a list of single-channel files as a single multichannel file
+- install looping to any file (for files with looping done in code)
+- remove unwanted channels (for layered exploration + action songs)
+- select a subsong in an audio bank
+- playback config such as volume or max playable time
+- apply complex real-time mixing
+- many other features
+
+Usage examples (open directly, name can be set freely):
+
+**bgm01-full.txtp**
+```
+# plays 2 files as a single one
+bgm01_intro.vag
+bgm01_loop.vag
+loop_mode = auto
+```
+
+**bgm-subsong10.txtp**
+```
+# plays subsong number 10
+bgm.sxd#10
+```
+
+**song01-looped.txtp**
+```
+# force looping an .mp3 from 10 seconds up to file end
+song02.mp3 #I 10.0
+```
+
+**music01-demux2.txtp**
+```
+# plays channels 3 and 4 only, removes rest
+music01.bfstm #C3,4
+```
+
+#### TXTM
+A text file named `.txtm` for some formats with companion files. It lists
+name combos determining which companion files to load for each main file.
+
+It is needed 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.
+Note that companion file order is usually important.
+
+Usage example (used when opening files in the left part of the list):
+```
+# Harry Potter and the Chamber of Secrets (PS2)
+exterior.mpf: exterior.mus,ext_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
+```
+```
+# Snack World (Switch) names for .awb (single .acb for all .awb, order matters)
+bgm.awb: bgm.acb
+bgm_DLC1.awb: bgm.acb
+```
+In rare cases you need to setup some extra flags
+```
+event_stream2.awb: event_stream2.acb
+event_stream2_dlc1.awb: event_stream2.acb
+event_stream2_dlc2.awb: event_stream2.acb
+event_stream2_dlc3.awb: event_stream2.acb
+# next "flag" allows both effect.acb and even_stream2.acb in the same file
+#@reset-pos
+effect.awb: effect.acb
+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.
+If a file that should isn't playing or looping, first make sure vgmstream is
+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
+modern versions (+1.4.x) you can configure plugin priority (go to *Preferences*
+then *playback > decoding* and move *vgmstream* higher or other plugins lower).
+
+In Audacious, vgmstream is set with slightly higher priority than FFmpeg,
+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
+time. Particularly, mpg123 plugin may steal formats that aren't even MP3,
+making impossible for vgmstream to play them properly.
+
+### Channel issues
+Some games layer a huge number of channels, that are disabled or downmixed
+during gameplay. The player may be unable to play those files (for example
+foobar can only play up to 8 channels, and Winamp depends on your sound
+card). For those files you can set the "downmix" option in vgmstream, that
+can reduce the number of channels to a playable amount. 
+
+Note that this type of downmixing is very generic (not meant to be used when
+converting to other formats), channels are re-assigned and volumes modified
+in simplistic ways, since it can't guess how the file should be properly
+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, 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
+"codec bitrate" (counts pure audio-only parts). This means bitrate may be
+slightly higher (or much higher, if file is bloated) than what encoder
+tools or other players may report.
+
+Calculating 100% correct codec bitrate usually needs manual reading of the whole
+file, slowing down opening files and needing extra effort by devs for minimal
+benefit, so it's not done.
+
+In some cases it's debatable what the codec bitrate is. Unlike MP3/AAC, 48kbps
+of raw Vorbis/Opus is unplayable/unusable unless it's packed into .ogg/wem/etc
+with extra data, that does increase final file size (thus bitrate) by some percent.
+
+Also, keep in mind video game audio bitrate isn't always a great indicator of quality.
+There are many factors in play like encoder, type of codec, sample rate and so on.
+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 easily 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. Or, perhaps you could to transmogrify
+the original header into something else, but for data preservation purposes
+it's preferable to leave it as-is (plus can use TXTH to play unsupported formats).
+
+If your main motivation for extracting is to rename or have loose files, remember
+you can simply use TXTP to point to a subsong, and name that `.txtp` whatever you
+want, without having to touch original data or needing custom extractors.
+
+### Cue formats
+Some formats that vgmstream supports (SQEX's .sab, CRI's .acb+awb, Wwise's .bnk+wem,
+Microsoft's .xss+.xwb....) are "cue" formats. The way these work is (more or less),
+they have a bunch of named audio "cues"/"events" in a section of the file, that are
+called to play one or multiple audio "waves"/"materials" in another section.
+
+Rather than handling cues, vgmstream shows and plays waves, then assigns cue names
+that point to the wave if possible, since vgmstream mainly deals with streamed/wave
+audio and simulating cues is out of scope. Figuring out a whole cue format can be a
+*huge* time investment, so handling waves only is often enough.
+
+Cues can be *very* complex, like N cues pointing to 1 wave with varying pitch, or
+1 cue playing one random wave out of 3. Sometimes not all waves are referenced by
+cues, or cues do undesirable effects that make only playing waves a good compromise.
+Simulating cues is better handled with external tools that allow more flexibility
+(for example, this project simulates Wwise's extremely complex cues/events by creating
+.TXTP telling vgmstream which config and waves to play, and one can filter desired
+cues/TXTP: https://github.com/bnnm/wwiser).
+
+## Logged errors and unplayable supported files
+Some formats should normally play, but somehow don't. In those cases plugins
+can print vgmstream's error info to console (for example, `.fsb` with an unknown
+codec, `.hca/awb` with missing decryption key, bank has no audio, `.txth` is
+malformed, or `.wav` has an incorrectly ripped size).
+
+Console location and format depends on plugin:
+- *foobar2000*: found in *View menu > Console*
+- *Winamp*: open vgmstream's config (*Preferences... > Plug-ins > vgmstream* + *Configure*
+  button) then press "Open Log"
+- *Audacious*: start with `audacious -V` from terminal
+- CLI utils: printed to stdout directly
+
+Only a few errors types are printed but may be helpful for more common cases.
+
+## Tagging
+Some of vgmstream's plugins support simple read-only tagging via external files.
+
+Tags are loaded from a text/M3U-like file named *!tags.m3u* in the song folder.
+You don't have to load your songs with this M3U though, but you can (for pre-made
+order). The format is meant to be both a quick playlist and tags, but the tagfile
+itself just 'looks' like an M3U. you can load files manually or using other playlists
+and still get tags.
+
+Format is:
+```
+# ignored comment
+# $GLOBAL_COMMAND (extra features)
+# @GLOBAL_TAG text (applies all following tracks)
+
+# %LOCAL_TAG text (applies to next track only)
+filename1
+# %LOCAL_TAG text (applies to next track only)
+filename2
+```
+Accepted tags depend on the player (foobar: any; Winamp: see ATF config, Audacious:
+few standard ones), typically *ALBUM/ARTIST/TITLE/DISC/TRACK/COMPOSER/etc*, lower
+or uppercase, separated by one or multiple spaces. Repeated tags overwrite previous
+(ex.- may define *@COMPOSER* multiple times for "sections"). It only reads up to
+current *filename* though, so any *@TAG* below would be ignored.
+
+*GLOBAL_COMMAND*s currently can be:
+- *AUTOTRACK*: sets *%TRACK* tag automatically (1..N as files are encountered
+  in the tag file).
+- *AUTOALBUM*: sets *%ALBUM* tag automatically using the containing dir as album.
+- *EXACTMATCH*: disables matching .txtp with regular files (explained below).
+
+Playlist title formatting (how tags are shown) should follow player's config, as
+vgmstream simply passes tags to the player. It's better to name the file lowercase
+`!tags.m3u` rather than `!Tags.m3u` (Windows accepts both but Linux is case sensitive).
+
+Example:
+```
+# @ALBUM    God Hand
+# @ARTIST   Masafumi Takada, Jun Fukuda
+# * Global tags apply to all songs, unless overwritten
+#   Better use ARTIST instead of ALBUMARTIST (more compatible)
+#   Tags usually go in CAPS for readability but no differences
+
+# $AUTOTRACK
+# * This adds TRACK tags automatically from 1 to N
+
+# %ARTIST   Masafumi Takada
+# %TITLE    Be ready for it
+godhand_ver1.adx
+
+#... (more songs)
+
+# %ARTIST   Jun Fukuda
+# %TITLE    Duel Storm
+Boss8_DevilHandHONKI_Ver9.adx
+
+#... (more songs)
+
+```
+
+Note that with global tags you don't need to put all files or info inside. This would be
+a perfectly valid *!tags.m3u*:
+```
+# @ALBUM    Game
+# @ARTIST   Various Artists
+```
+
+### Compatibility and non-English filenames and tags
+For best compatibility save `!tags.m3u` as *"ANSI"* or *"UTF-8" (with BOM)*.
+
+Tags and filenames using extended characters (like Japanese) should work, as long
+as `!tags.m3u` is saved as *"UTF-8 with BOM"* (UTF-8 is a way to define non-English
+characters, and BOM is a helper "byte-order" mark). Windows' *notepad* creates files
+*"with BOM"* when selecting UTF-8 encoding in *save as* dialog, or you may use other
+programs like *notepad++.exe* to convert them.
+
+More exactly, vgmstream needs the file saved in *UTF-8* to match tags and filenames
+(and ignores *BOM*), while foobar/Winamp won't understand UTF-8 *filenames* unless
+`.m3u` is saved *with BOM* (ignoring tags). Whereas if saved in what Windows calls
+"Unicode" (UTF-16) neither may work.
+
+Conversely, if your *filenames* only use English/ANSI characters you may ommit *BOM*,
+and if your tags are English only you may save the `.m3u` as ANSI. Or if you only use
+`!tags.m3u` for tags and not for opening files (for example opening them manually
+or with a `playlist.m3u8`) you won't need BOM either.
+
+Other players may not need BOM (or CRLF), but for consistency use them when dealing
+with non-ASCII names and tags.
+
+### Tags with spaces
+Some players like foobar accept tags with spaces. To use them surround the tag
+with both characters.
+```
+# @GLOBAL TAG WITH SPACES@ text
+# ...
+# %LOCAL TAG WITH SPACES% text
+filename1
+```
+As a side effect if text has @/% inside you also need them: `# @ALBUMARTIST@ Tom-H@ck`
+
+For interoperability with other plugins, consider using only common tags without spaces,
+and tags that are commonly accepted in all players like ARTIST instead of ALBUMARTIST.
+
+### ReplayGain
+foobar2000/Winamp can apply the following replaygain tags (if ReplayGain is
+enabled in preferences):
+```
+# %replaygain_track_gain N.NN dB
+# %replaygain_track_peak N.NNN
+# @replaygain_album_gain N.NN dB
+# @replaygain_album_peak N.NNN
+```
+
+### TXTP matching
+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
+BGM01.adx #P 3.0.txtp
+# @TITLE    Title2
+BGM02.wav
+```
+**config.m3u**
+```
+# matches "Title1" (1:1)
+BGM01.adx #P 3.0.txtp
+# matches "Title1" (plain file matches config tag)
+BGM01.adx
+# matches "Title2" (config file matches plain tag)
+BGM02.wav #P 3.0.txtp
+# doesn't match anything (different config can't match)
+BGM01.adx #P 10.0.txtp
+```
+
+Since it matches when a tag is found, some cases that depend on order won't work.
+You can disable this feature manually then:
+
+**!tags.m3u**
+```
+# $EXACTMATCH
+#
+# %TITLE    Title3 (without config)
+BGM01.adx
+# %TITLE    Title3 (with config)
+BGM01.adx #I 1.0 90.0 .txtp
+```
+**config.m3u**
+```
+# Would match "Title3 (without config)" without "$EXACTMATCH", as it's found first
+# Could use "BGM01.adx.txtp" as first entry in !tags.m3u instead (different configs won't match)
+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
+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.
+
+When tags change behavior varies depending on player:
+- *Winamp*: should refresh tags when a different file is played.
+- *foobar2000*: needs to force refresh (for reasons outside vgmstream's control)
+  - **select songs > shift + right click > Tagging > Reload info from file(s)**.
+- *Audacious*: files need to be re-added 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. You may try this python script to make the
+base file: https://raw.githubusercontent.com/bnnm/vgm-tools/master/py/tags-maker.py
+
+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 mixable 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/
+- foo_external_tags: https://foobar.hyv.fi/?view=foo_external_tags
+
+
+## Virtual TXTP files
+Some of vgmstream's plugins (and CLI) 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
+filename.
+
+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
+# notice the full filename, then #(config), then ".txtp" (spaces are optional)
+bank_bgm_full.nub  #s1  .txtp
+bank_bgm_full.nub  #s10 .txtp
+```
+
+Combine with tagging (see above) for extra fun OST-like config.
+```
+# @ALBUM    GOD HAND
+
+# play 1 loop, delay and do a longer fade
+# %TITLE    Too Hot !!
+circus_a_mix_ver2.adx       #l 1.0 #d 5.0 #f 15.0 .txtp
+
+# play 1 loop instead of the default 2 then fade with the song's internal fading
+# %TITLE    Yet... Oh see mind
+boss2_3ningumi_ver6.adx     #l 1.0  #F .txtp
+
+...
+```
+
+You can also use it in CLI for quick access to some txtp-exclusive functions:
+```
+# force change sample rate to 22050 (don't forget to use " with spaces)
+vgmstream-cli -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-existent files referenced in a `.m3u`, while other players may filter them
+first.
+
+You can use this python script to autogenerate one `.txtp` per virtual-txtp:
+https://github.com/vgmstream/vgmstream/tree/master/cli/tools/txtp_dumper.py
+Drag and drop the `.m3u`, or any text file with .txtp  (it has CLI options
+to control output too).
+
+
+## Sequences and streams
+Roughly, there are two types of game audio:
+- streams: prerecorded audio where all instruments are pre-mixed into a single
+  file, often compressed with some custom format.
+- sequences: series of instrument notes, typically in MIDI-like formats with
+  a bank of instrument sounds.
+
+As the name implies, vgmstream plays "streams". Old games mainly use sequences
+(very small and more dynamic), while other games use streams (easier to handle
+but lot bigger and sometimes CPU-intensive).
+
+vgmstream's internals are tailored to play streams so, in other words, it's not
+possible to add support for sequenced audio unless massive changes were done,
+basically becoming another program entirely. There are other projects better
+suited for playing sequences.