Cool_Tools/vgmstream
1
0
Fork 0
mirror of https://github.com/vgmstream/vgmstream.git synced 2025-02-19 12:04:42 +01:00
Code Issues Packages Projects Releases Wiki Activity

Doc

Browse Source
This commit is contained in:
bnnm 2020-11-15 22:46:22 +01:00
parent 5c58e2fc7f
commit 6c59ae0d0f
1 changed files with 111 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

181
README.md
View File

@ -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. 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. 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** 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` 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 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 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 to a temp dir using the respective utility program (which must be installed
and accessible) and then loaded. 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: You can use this python script to autogenerate one `.txtp` per subsong:
https://github.com/losnoco/vgmstream/tree/master/cli/txtp_maker.py 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 Put in the same dir as test.exe/vgmstream_cli, then to drag-and-drop files with
to `txtp_maker.py`. subsongs to `txtp_maker.py`.
### Renamed files ### Renamed files
A few extensions that vgmstream supports clash with common ones. Since players 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 like foobar or Winamp don't react well to that, they may be renamed to make
them playable through vgmstream. them playable through vgmstream.
- .aac to .laac (tri-Ace games) - `.aac` to `.laac` (tri-Ace games)
- .ac3 to .lac3 (standard AC3) - `.ac3` to `.lac3` (standard AC3)
- .aif to .laif or .aiffl or .aifcl (standard Mac AIF, Asobo AIF, Ogg) - `.aif` to `.laif` (standard Mac AIF, Asobo AIF, Ogg)
- .aiff/aifc to .aiffl/aifcl (standard Mac AIF) - `.aiff/aifc` to `.laiffl/laifc` (standard Mac AIF)
- .asf to .lasf (EA games, Argonaut ASF) - `.asf` to `.lasf` (EA games, Argonaut ASF)
- .bin to .lbin (various) - `.bin` to `.lbin` (various)
- .flac to .lflac (standard FLAC) - `.flac` to `.lflac` (standard FLAC)
- .mp2 to .lmp2 (standard MP2) - `.mp2` to `.lmp2` (standard MP2)
- .mp3 to .lmp3 (standard MP3) - `.mp3` to `.lmp3` (standard MP3)
- .mp4 to .lmp4 (standard M4A) - `.mp4` to `.lmp4` (standard M4A)
- .mpc to .lmpc (standard MPC) - `.mpc` to `.lmpc` (standard MPC)
- .ogg to .logg (standard OGG) - `.ogg` to `.logg` (standard OGG)
- .opus to .lopus (standard OPUS or Switch OPUS) - `.opus` to `.lopus` (standard OPUS or Switch OPUS)
- .stm to .lstm (Rockstar STM) - `.stm` to `.lstm` (Rockstar STM)
- .wav to .lwav (standard WAV) - `.wav` to `.lwav` (standard WAV)
- .wma to .lwma (standard WMA) - `.wma` to `.lwma` (standard WMA)
- .(any) to .vgmstream (FFmpeg formats or TXTH) - `.(any)` to `.vgmstream` (FFmpeg formats or TXTH)
Command line tools don't have this restriction and will accept the original Command line tools don't have this restriction and will accept the original
filename. filename.
The main advantage to rename them is that vgmstream may use the file's 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 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. may work as a last resort to make a file playable.
Some plugins have options that allow any extension (common or unknown) to be 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. without modification) first, since vgmstream doesn't attempt to support them.
The easiest way to do this is using VGMToolBox's "Video Demultiplexer" option 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 For standard videos formats (`.avi`, `.mp4`, `.webm`, `.m2v`, `.ogv`, etc) not supported
by VGMToolBox FFmpeg binary may work: by VGMToolBox, FFmpeg binary may work:
- `ffmpeg.exe -i (input file) -vn -acodec copy (output file)` - `ffmpeg.exe -i (input file) -vn -acodec copy (output file)`
Output extension may need to be adjusted to some appropriate audio file depending 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 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). 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. on the internet.
### Companion files ### Companion files
Some formats have companion files with external looping info, and should be Some formats have companion files with external info, that should be left together:
left together. - `.mus`: playlist for `.acm`
- .mus (playlist for .acm) - `.ogg.sli` or `.sli`: loop info for `.ogg`
- .pos (loop info for .wav, and sometimes .ogg) - `.ogg.sfl` : loop info for `.ogg`
- .ogg.sli or .sli (loop info for .ogg) - `.opus.sli`: loop info for `.opus`
- .ogg.sfl (loop info for .ogg) - `.pos`: loop info for .wav
- .vgmstream.pos (loop info for FFmpeg formats) - `.vgmstream.pos`: loop info for FFmpeg formats
- also possible for certain extensions like .lflac.pos - `.acb`: names for `.awb`
- `.xsb`: names for `.xwb`
Similarly some formats split header and/or data in separate files (.sgh+sgd, Similarly some formats split header+body data in separate files, examples:
.wav.str+.wav, (file)_L.dsp+(file)_R.dsp, etc). vgmstream will also detect - `.abk`+`.ast`
and use those as needed and must be together, even if only one of the two - `.bnm`+`.apm/wav`
will be used to play. - `.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 Generally companion files are named the same (`bgm.awb`+`bgm.acb`), or internally
instead of being listed in the main file (e.g. .mpf+.mus). In these cases, you point to another file `sfx.sb0`+`STREAM.sb0`. A few formats may have different names
can use TXTM format to specify associated companion files. See below for more which are hardcoded instead of being listed in the main file (e.g. `.mpf+.mus`).
information. 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 A special case of the above is "dual file stereo", where 2 similarly named mono
and loop end sample. For FFmpeg formats (.vgmstream.pos) it may optionally files are fused together to make 1 stereo song.
have total samples after those. - `(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 ### Decryption keys
Certain formats have encrypted data, and need a key to decrypt. vgmstream 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 will try to find the correct key from a list, but it can be provided by
a companion file: 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 - May be followed by 2 byte AWB scramble key for newer HCA
- .fsb: .fsbkey (decryption key, in hex) - `.fsb`: `.fsbkey` (decryption key, in hex)
- .bnsf: .bnsfkey (decryption key, a string up to 24 chars) - `.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. (for a single file). The format is made up to suit vgmstream.
### Artificial files ### 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. **GENH**: a byte header placed right before the original data, modyfing it.
The resulting file must be (name).genh. Contains static header data. 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**: 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 `.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 *TXTH* is recomended over *GENH* as it's far easier to create and has many
more functions. more functions.
For files that already play, sometimes they are used by the game in various 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 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 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 **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`), 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, list of separate channel files to join as a single multichannel file,
subsong index (ex. `bgm.sxd#10`), per-file configurations like number of 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 **TXTM**: text file named `.txtm` for formats with companion files. It lists
name combos determining which companion files to load for each main file. 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 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. Note that companion file order is usually important.
Usage example: Usage example:
@ -301,6 +333,10 @@ Usage example:
entrance.mpf:entrance.mus,entrance_o.mus entrance.mpf:entrance.mus,entrance_o.mus
willow.mpf:willow.mus,willow_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 Creation of those files is meant for advanced users, docs can be found in
vgmstream source. 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. try to remove a few other plugins.
foobar's FFmpeg plugin and foo_adpcm are known to cause issues, but in 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, 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. However other plugins may set themselves higher, stealing formats instead.
If current Audacious version doesn't let to change plugin priority you may 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 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 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`. 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 ## Tagging
@ -400,8 +437,8 @@ enabled in preferences):
``` ```
### TXTP matching ### TXTP matching
To ease *TXTP* config, tags with plain files will match .txtp with config, and tags To ease *TXTP* config, tags with plain files will match `.txtp` with config, and tags
with .txtp config also match plain files: with `.txtp` config also match plain files:
**!tags.m3u** **!tags.m3u**
``` ```
# @TITLE Title1 # @TITLE Title1
@ -441,7 +478,7 @@ BGM01.adx #I 1.0 90.0 .txtp
### Issues ### Issues
If your player isn't picking tags make sure vgmstream is detecting the song 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 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 to make sure *options > titles > advanced title formatting* checkbox is set and
the format defined. the format defined.
@ -453,11 +490,11 @@ When tags change behavior varies depending on player:
- *Audacious*: files need to be readded to the playlist - *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 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 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), 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, 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: foobar2000 has other plugins (with write support) that may be of use:
- m-TAGS: http://www.m-tags.org/ - 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 ## 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. with playlists let you make quick song configs.
Normally you can create a physical .txtp file that points to another file with 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. 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: in a `.m3u` playlist:
``` ```
# playlist that opens subsongs directly without having to create .txtp # 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" 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 ## Supported codec types
Quick list of codecs vgmstream supports, including many obscure ones that Quick list of codecs vgmstream supports, including many obscure ones that
are used in few games. are used in few games.
- PCM 16-bit - PCM 16-bit
- PCM 8-bit (signed/unsigned) - PCM 8-bit (signed, unsigned)
- PCM 4-bit (signed/unsigned) - PCM 4-bit (signed, unsigned)
- PCM 32-bit float - PCM 32-bit float
- u-Law/a-LAW - u-Law/a-LAW
- CRI ADX (standard, fixed, exponential, encrypted) - CRI ADX (standard, fixed, exponential, encrypted)