mirror of
https://github.com/vgmstream/vgmstream.git
synced 2024-09-24 03:08:21 +02:00
Improve docs
This commit is contained in:
KatieFrogs
parent
c014254531
commit
020566fa69
110
README.md
110
README.md
@ -1,22 +1,22 @@
|
||||
# vgmstream
|
||||
This is vgmstream, a library for playing streamed (pre-recorded) audio from
|
||||
video games.
|
||||
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, 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, playing a format's multiple internal songs separately
|
||||
- many types of companion files (data split in multiple files) and custom containers
|
||||
- encryption keys, internal stream names, and many other unusual cases found in game audio
|
||||
- TXTH function, to add external support for extra formats (including raw audio in many forms)
|
||||
- TXTP function, for real-time and per-file config (like forced looping, removing
|
||||
channels, playing certain subsong, or fusing together multiple files as a single one)
|
||||
- simple external tagging via .m3u files
|
||||
- plugins available for various common players and O.S.
|
||||
- [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](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](USAGE.md#tagging) via .m3u files.
|
||||
- [Plugins](#getting-vgmstream) are available for various media player software and operating systems.
|
||||
|
||||
Latest development is here: https://github.com/vgmstream/vgmstream/
|
||||
The main development repository: https://github.com/vgmstream/vgmstream/
|
||||
|
||||
Automated builds with the latest changes: https://vgmstream.org/downloads
|
||||
|
||||
@ -24,57 +24,71 @@ Common releases: https://github.com/vgmstream/vgmstream/releases
|
||||
|
||||
Help can be found here: https://www.hcs64.com/
|
||||
|
||||
More docs: https://github.com/vgmstream/vgmstream/tree/master/doc
|
||||
More documentation: https://github.com/vgmstream/vgmstream/tree/master/doc
|
||||
|
||||
## Getting vgmstream
|
||||
There are multiple end-user bits:
|
||||
- a command line decoder called *test.exe/vgmstream-cli*
|
||||
- a Winamp plugin called *in_vgmstream*
|
||||
- a foobar2000 component called *foo_input_vgmstream*
|
||||
- an XMPlay plugin called *xmp-vgmstream*
|
||||
- an Audacious plugin called *libvgmstream*
|
||||
- a command line player called *vgmstream123*
|
||||
There are multiple end-user components:
|
||||
- [test.exe/vgmstream-cli](USAGE.md#testexevgmstream-cli-command-line-decoder): A command-line decoder.
|
||||
- [in_vgmstream](USAGE.md#in_vgmstream-winamp-plugin): A Winamp plugin.
|
||||
- [foo_input_vgmstream](USAGE.md#foo_input_vgmstream-foobar2000-plugin): A foobar2000 component.
|
||||
- [xmp-vgmstream](USAGE.md#xmp-vgmstream-xmplay-plugin): An XMPlay plugin.
|
||||
- [vgmstream.so](USAGE.md#audacious-plugin): An Audacious plugin.
|
||||
- [vgmstream123](USAGE.md#vgmstream123-command-line-player): A command-line player.
|
||||
|
||||
Main lib (plain *vgmstream*) is the code that handles internal conversion, while the
|
||||
above components are what you use to actually get sound.
|
||||
The main library (plain *vgmstream*) is the code that handles the internal conversion, while the
|
||||
above components are what you use to get sound.
|
||||
|
||||
See *components* in *usage guide* for install instructions and explanations. The aim
|
||||
is feature parity, but there are a few differences between them (due to missing
|
||||
implementation in vgmstream's side, or lack of support in target player/API/etc).
|
||||
See [components](doc/USAGE.md#components) in the *usage guide* for install instructions and
|
||||
explanations. The aim is feature parity, but there are a few differences between them due to
|
||||
missing implementation on vgmstream's side or lack of support in target player or API.
|
||||
|
||||
### Windows
|
||||
You should get `vgmstream-win.zip` (bundle of various components) or
|
||||
`foo_input_vgmstream.fb2k-component` (installable foobar2000 plugin) from the
|
||||
latest pre-built binaries:
|
||||
https://vgmstream.org/downloads
|
||||
You should get `vgmstream-win.zip`, which also bundles various components, or
|
||||
`foo_input_vgmstream.fb2k-component` for the installable foobar2000 plugin from the
|
||||
latest prebuilt binaries on our website:
|
||||
- https://vgmstream.org/downloads
|
||||
|
||||
You can also try getting them from the (infrequently updated) releases:
|
||||
https://github.com/vgmstream/vgmstream/releases
|
||||
You can also get them from the less frequently updated releases on GitHub:
|
||||
- https://github.com/vgmstream/vgmstream/releases
|
||||
|
||||
If the above links fail you may try alt, recent-ish versions here:
|
||||
https://github.com/bnnm/vgmstream-builds/raw/master/bin/vgmstream-latest-test-u.zip
|
||||
If the above links fail, you may also try the alternative, somewhat recent 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 them from source as well (see *build guide*).
|
||||
If you prefer, you may compile the components from source as well, see the
|
||||
[build guide](doc/BUILD.md) for more information.
|
||||
|
||||
### Linux
|
||||
Generally you need to build vgmstream's components manually (see *build guide*). For
|
||||
a quick build call `./make-build-cmake.sh` (for Debian/Ubuntu-style distros, installs
|
||||
various deps first so you may prefer to call commands manually).
|
||||
For convenience, releases distribute a command-line decoder in `vgmstream-cli.zip`. It is
|
||||
statically linked and should work on all systems running Linux kernel v3.2 and above.
|
||||
- https://vgmstream.org/downloads
|
||||
- https://github.com/vgmstream/vgmstream/releases
|
||||
|
||||
Releases also distribute a static version of the CLI tool (kernel v3.2+).
|
||||
https://vgmstream.org/downloads
|
||||
https://github.com/vgmstream/vgmstream/releases
|
||||
For Arch Linux users, the `vgmstream-git` package is available in AUR:
|
||||
- https://aur.archlinux.org/packages/vgmstream-git/
|
||||
|
||||
### Mac
|
||||
Follow the *build guide* instructions. You can probably use Linux's script above with
|
||||
some tweaks.
|
||||
Building from source will also give you *vgmstream.so*, an Audacious plugin, and *vgmstream123*,
|
||||
a command-line player.
|
||||
|
||||
When building from source code, many components have to be installed or compiled separately. The
|
||||
[build guide](doc/BUILD.md) describes this process in more detail. For a quick build on Debian and
|
||||
Ubuntu-style distributions, run `./make-build-cmake.sh`. The script will be installing various
|
||||
dependencies, so you may prefer to copy the commands from the file and run them one by one.
|
||||
|
||||
### macOS
|
||||
Install using [Homebrew](https://brew.sh/):
|
||||
- https://formulae.brew.sh/formula/vgmstream
|
||||
|
||||
Or follow the [build guide](doc/BUILD.md) to build it yourself. You could also probably use the
|
||||
Linux script above with some tweaks.
|
||||
|
||||
|
||||
## More info
|
||||
- [Usage guide](doc/USAGE.md)
|
||||
- [List of supported audio formats](doc/FORMATS.md)
|
||||
- [Build guide](doc/BUILD.md)
|
||||
- [TXTH info](doc/TXTH.md)
|
||||
- [TXTP info](doc/TXTP.md)
|
||||
- [TXTH file format](doc/TXTH.md)
|
||||
- [TXTP file format](doc/TXTP.md)
|
||||
|
||||
|
||||
Enjoy! *hcs*
|
||||
|
||||
462
doc/BUILD.md
462
doc/BUILD.md
@ -1,157 +1,27 @@
|
||||
# vgmstream build help
|
||||
This document explains how to build each of vgmstream's components and libs.
|
||||
This document explains how to build each of vgmstream's components and libraries.
|
||||
|
||||
|
||||
## Compilation requirements
|
||||
Because each module has different quirks one can't use a single tool for everything. You should be able to build most using a standard *compiler* (GCC/MSVC/Clang) using common *build systems* (scripts/CMake/autotools) in any typical *OS* (Windows/Linux/Mac).
|
||||
vgmstream can be compiled using one of many build scripts that are available in this repository. Components are detailed below, but if you are new to development you probably want one of these:
|
||||
- **Windows**: [simple scripts](#simple-scripts-builds) + [Visual Studio](#microsofts-visual-c-msvc--visual-studio--msbuild-compiler)
|
||||
- **Linux**: [Cmake](#cmake-builds) + [GCC](#gcc--make-compiler)
|
||||
- **macOS**: [Cmake](#cmake-builds) + [Clang](#clang-compiler)
|
||||
- **Web**: [Cmake](#cmake-builds) + [Emscripten](#emscripten-compiler)
|
||||
|
||||
64-bit support may work but has been minimally tested, since main use of vgmstream is plugins for 32-bit players (extra codec libs for Windows are included for 32-bit only ATM, and there may be bugs in some codecs and formats).
|
||||
Because each module has different quirks one can't use a single tool for everything. You should be able to build most using a standard *compiler* (GCC/MSVC/Clang) using common *build systems* (scripts/CMake/autotools) in any typical *OS* (Windows/Linux/macOS).
|
||||
|
||||
Components are detailed below, but if you are new to development you probably want:
|
||||
- Windows: Visual Studio + simple scripts
|
||||
- Linux: GCC + CMake
|
||||
- Max: Clang + CMake
|
||||
On **Windows**, 64-bit support may work but has been minimally tested, since the main use of vgmstream is plugins for 32-bit players. Windows libraries for extra codecs are included for 32-bit only at the moment, and there may be bugs in some codecs and formats.
|
||||
|
||||
Though it's rather flexible (like using Windows with GCC and autotools), some combos may be a bit more complex to get working depending on your system and other factors.
|
||||
|
||||
|
||||
### GCC / Make (compiler)
|
||||
Common C compiler, most development is done with this.
|
||||
|
||||
On Windows you need one of these somewhere in PATH:
|
||||
- MinGW-w64 (32bit version): https://sourceforge.net/projects/mingw-w64/
|
||||
- Use this for easier standalone executables
|
||||
- Latest online installer with any config should work (for example: gcc-8.1.0, i686, win32, sjlj).
|
||||
https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/installer/mingw-w64-install.exe/download
|
||||
- Get from sourceforge page > "files" tab > scroll below > MingGW-W64-install.exe
|
||||
- Or download and unzip portable package:
|
||||
https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/8.1.0/threads-win32/sjlj/i686-8.1.0-release-win32-sjlj-rt_v6-rev0.7z/download
|
||||
- Get from sourceforge page > "files" tab > Toolchains targetting Win32 > Personal Builds > mingw-builds > some version zip
|
||||
- MSYS2 with the MinGW-w64_shell (32bit) package: https://msys2.github.io/
|
||||
- Resulting binaries may depend on `msys*.dll`.
|
||||
|
||||
On Linux it should be included by default in the distribution, or can be easily installed using the distro's package manager (for example `sudo apt-get install gcc g++ make`).
|
||||
|
||||
On Mac may be installed with a package manager like *Homebrew*, but using *Clang* is probably easier.
|
||||
|
||||
Any not-too-ancient versions should work, since vgmstream uses standard C. GCC usually comes with *Make*, a program that can be used to build vgmstream.
|
||||
|
||||
### Microsoft's Visual C++ (MSVC) / Visual Studio / MSBuild (compiler)
|
||||
Alt C compiler (Windows only), auto-generated builds for Windows use this. Bundled in:
|
||||
- Visual Studio (2015/2017/2019/latest): https://www.visualstudio.com/downloads/
|
||||
|
||||
Visual Studio Community (free) should work, but you may need to register after a trial period. Even after trial you can still use *MSBuild*, command-line tool that actually does all the building, calling the *MSVC* compiler (Visual Studio itself is just an IDE for development and not actually needed).
|
||||
|
||||
Instead of the full (usually huge) Visual Studio, you can also get "Build Tools for Visual Studio", variation that only installs *MSBuild* and necessary files without the IDE. Usually found in the above link, under "Tools for Visual Studio" (or google as MS's links tend to move around).
|
||||
|
||||
When installing check the "Desktop development with C++" group, and optionally select "MFC support" and "ATL support" sub-options to build foobar2000 plugin (you can modify that or re-install IDE later, by running installed "Visual Studio Installer"). You could include MSVC v141 (2017) compatibility too just in case, since it's mainly tested with that.
|
||||
|
||||
Older versions of MSVC (2010 and earlier) have limited C support and may not work with latest commits, while reportedly beta/new versions aren't always very stable. Also, only projects (`.vcxproj`) for VS2015+ are included (CMake may be able to generate older `.vcproj` if you really need them). Some very odd issues affecting MSVC only have been found and fixed before. Keep in mind all of this if you run into problems.
|
||||
|
||||
### Clang (compiler)
|
||||
Alt C compiler, reportedly works fine on Mac and may used as a replacement of GCC without issues.
|
||||
- https://releases.llvm.org/download.html
|
||||
|
||||
Should be usable on Linux and possibly Windows with CMake. For default Makefiles may need to set compiler vars appropriately (CC=clang AR=llvm-ar and so on).
|
||||
|
||||
### Simple scripts (builds)
|
||||
Default build scripts included in source that can compile vgmstream, though limited in some ways.
|
||||
|
||||
**For MSVC**: there is a default Visual Studio `.sln` that should be up to date (run `./msvc-build-init.bat` first, or see the foobar section to get extra dependencies manually, then open). A PowerShell script also automates compilation (on Windows 7 may need recent .NET framework and PowerShell versions), simply run `./msvc-build.bat`.
|
||||
|
||||
First you may need to either open the `.sln` and change project compiler (*PlatformToolset*) and SDK (*WindowsTargetPlatformVersion*) to your installed version, or edit `msvc-build.ps1` and set the variables near *CONFIG*. To avoid modifying files you can also create a file named `msvc-build.config.ps1` with:
|
||||
```
|
||||
# - toolsets: "" (p), "v140" (MSVC 2015), "v141" (MSVC 2017), "v141_xp" (XP support), "v142" (MSVC 2019), etc
|
||||
# - sdks: "" (default), "7.0" (Win7 SDK), "8.1" (Win8 SDK), "10.0" (Win10 SDK), etc
|
||||
$toolset = "142"
|
||||
$sdk = "10.0"
|
||||
```
|
||||
It's also possible to call MSBuild and pass those values from the CMD, see foobar section for an example.
|
||||
|
||||
Once finished resulting binaries are in the *./Release* folder. Remember you need to copy extra `.dll` to run them (see [USAGE.md](USAGE.md)).
|
||||
|
||||
**For GCC/CLang**: there are basic Makefiles that work like usual with *make* (like `make vgmstream_cli EXTRA_CFLAGS="-DVGM_DEBUG_OUTPUT`). Artifacts are usually in their subdir (*./cli*, *./winamp*, etc).
|
||||
|
||||
On Windows this compiles with extra libs enabled by default. On Linux there is no fancy autodetection (try CMake or autotools for that), so you need to make sure libs are in your system and pass flags to enable them manually (install/compile libs then `make vgmstream_cli VGM_VORBIS=1 ...`). Check or run `make-build.sh` for a basic example that builds CLI and vgmstream123 with most libs enabled for a Ubuntu-style distro (if you get errors on your system just tweak or comment out offending parts).
|
||||
|
||||
Linux example:
|
||||
```
|
||||
sudo apt-get install -y git
|
||||
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
# in case they weren't set
|
||||
chmod +x version-get.sh version-make.sh make-build.sh
|
||||
|
||||
# warning: installs stuff, check all "apt install"
|
||||
./make-build.sh
|
||||
```
|
||||
|
||||
### CMake (builds)
|
||||
Tool used to generate common build files (for *make*, *VS/MSBuild*, etc), that in turn can be used to compile vgmstream's modules instead of existing scripts/files. Needs v3.6 or later:
|
||||
A tool used to generate common build files (for *make*, *VS/MSBuild*, etc), that in turn can be used to compile vgmstream's modules instead of using the existing scripts and files. Needs v3.6 or later:
|
||||
- https://cmake.org/download/
|
||||
|
||||
If you wish to use CMake see [CMAKE.md](CMAKE.md). Some extra info is only mentioned in this doc though.
|
||||
|
||||
Note that doing in-source builds of CMake (`cmake .` / selecting `./vgmstream` as output dir) is not recommended and may clobber default build files (try `cmake -S . -B build` / using some `./build` subfolder).
|
||||
|
||||
### autotools (builds)
|
||||
Autogenerated *make* scripts, used by some modules (mainly Audacious for Linux, and external libs).
|
||||
|
||||
For Windows you must include GCC, and Linux's sh tool in some form in PATH. Simplest would be installing *MinGW-w64* for `gcc.exe` (and related tools), and *Git* for `sh.exe`, and making PATH point their bin dir.
|
||||
- ex. `C:\mingw\i686-8.1.0-release-win32-sjlj-rt_v6-rev0\mingw32\bin` and `C:\Git\usr\bin`
|
||||
- Both must be installed/copied in a dir without spaces (with spaces autoconf seemingly works but creates buggy files)
|
||||
- If you don't have Git, try compiled GNU tools for Windows (http://gnuwin32.sourceforge.net/packages.html)
|
||||
|
||||
A trick on Windows is that you can temporary alter PATH variable in `.bat` scripts (PATH is used to call programs in Windows without having to write full path to .exe)
|
||||
```
|
||||
set PATH=%PATH%;C:\mingw\i686-8.1.0-release-win32-sjlj-rt_v6-rev0\mingw32\bin
|
||||
set PATH=%PATH%;C:\Git\usr\bin
|
||||
gcc.exe (...)
|
||||
```
|
||||
|
||||
For Linux, GCC/make/autotools should be included already, or install with a package manager (`sudo apt-get install gcc g++ make autoconf automake libtool`), also depends on *Make*.
|
||||
|
||||
Typical usage involves `./configure` (creates Makefiles) + `make` (compiles) + `make install` (copies results), but varies slightly depending on module/lib (explained later).
|
||||
|
||||
External libs using autotools can be compiled on Windows too, try using `sh.exe ./configure`, `mingw32-make.exe`, `mingw32-make.exe install` instead. Also for older libs, call `sh.exe ./configure` with either `--build=mingw32`, `--host=mingw32` or `--target-os=mingw32` (varies) for older configure. You may also need to use `mingw32-make.exe LDFLAGS="-no-undefined -static-libgcc" MAKE=mingw32-make.exe` so that `.dll` are correctly generated.
|
||||
|
||||
### Git (extras)
|
||||
Code version control for development. Optional, used to auto-generate version numbers:
|
||||
- https://git-scm.com/download
|
||||
|
||||
Remember Git can only be used if you clone the vgmstream repo (not with `.zip` sources).
|
||||
|
||||
On Windows, Git also comes with typical Linux utils (in the usr\bin dir), that can help when compiling some extra components.
|
||||
|
||||
### Extra libs (extras)
|
||||
Optional codec. See *External libraries* for full info.
|
||||
|
||||
On Windows most libs are pre-compiled and included to simplify building (since they can be quite involved to compile).
|
||||
|
||||
On Linux you usually need dev packages of each (for example `libao-dev` for vgmstream123, `libvorbis-dev` for Vorbis, and so on) and they should be picked by CMake/autotool scripts.
|
||||
|
||||
With no extra libs (or only some) enabled vgmstream works fine, but some advanced formats/codecs won't play. See *External libraries* for info about those extra codecs.
|
||||
|
||||
|
||||
## Compiling modules
|
||||
|
||||
### CLI (test.exe/vgmstream-cli) / Winamp plugin (in_vgmstream) / XMPlay plugin (xmp-vgmstream)
|
||||
|
||||
**With GCC/Clang**: there are various ways to build it, each with some differences; you probably want CMake described below.
|
||||
|
||||
Simplest way is using the *./Makefile* in the root folder, see inside for options. For compilation flags check the *Makefile* in each folder. You may need to manually rebuild if you change a *.h* file (`make clean`). On Windows this will build with external libs enabled, but Linux can't ATM.
|
||||
|
||||
Also, on Linux you can't build *in_vgmstream* and *xmp-vgmstream* (given they are Windows DLLs...). Makefiles have been used in the past to cross-compile from Linux with MingW headers though, but can't generate native Win code at the moment (should be fixable with some effort).
|
||||
|
||||
*Autotools* should build and install it as `vgmstream-cli`, this is explained in detail in the Audacious section. It enables (some) extra codecs. Some Linux distributions like Arch Linux include pre-patched vgmstream with most libraries, you may want that instead:
|
||||
- https://aur.archlinux.org/packages/vgmstream-git/
|
||||
|
||||
If you use Mac (or Linux), there is a *Homebrew* script that may automate the process (uses CMake):
|
||||
- https://formulae.brew.sh/formula/vgmstream
|
||||
|
||||
You may try CMake instead as it may be simpler and handle libs better. Some older distros may not work though (CMake version needs to recognize FILTER command). You may also need to install resulting artifacts manually. Check the *CMAKE.md* doc for some extra info too.
|
||||
```
|
||||
On **Linux**, the CMake script can automatically download and build the source code for dependencies that it requires. It is also capable of creating a statically linked binary for distribution purposes. The build steps with CMake are as follows:
|
||||
```sh
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y gcc g++ make build-essential git
|
||||
sudo apt-get install -y libmpg123-dev libvorbis-dev libspeex-dev
|
||||
@ -163,13 +33,209 @@ sudo apt-get install -y cmake
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
|
||||
# for older versions try "cmake ." instead
|
||||
cmake -S . -B build
|
||||
mkdir -p build
|
||||
cd build
|
||||
cmake ..
|
||||
make
|
||||
```
|
||||
You can compile faster using `make -j 5` instead of the last `make` command (replace `5` with the number of cores your CPU has plus one), but please note that, with multiple jobs, in case any issues occur the output will become useless.
|
||||
|
||||
Windows CMD .bat example (with some debugging on):
|
||||
The output files are `build/cli/vgmstream-cli` (CLI decoder), `build/cli/vgmstream123` (CLI player), and `build/audacious/vgmstream.so` (Audacious plugin).
|
||||
|
||||
For more information and options see the full guide in the [CMAKE.md](CMAKE.md) file.
|
||||
|
||||
Note that doing in-source builds of CMake (`cmake .`) is not recommended, as that may clobber default build files.
|
||||
|
||||
### Simple scripts (builds)
|
||||
Default build scripts are included in the source that can compile vgmstream, though limited in some ways.
|
||||
|
||||
**For MSVC**: there is a default Visual Studio `.sln` file that should be up to date (run `./msvc-build-init.bat` first, or see the foobar section to get extra dependencies manually, then open). A PowerShell script also automates compilation (on **Windows 7** may need recent .NET framework and PowerShell versions), simply run `./msvc-build.bat`.
|
||||
|
||||
First, you may need to either open the `.sln` and change project compiler (*PlatformToolset*) and SDK (*WindowsTargetPlatformVersion*) to your installed version, or edit `msvc-build.ps1` and set the variables near *CONFIG*. To avoid modifying files, you can also create a file named `msvc-build.config.ps1` with:
|
||||
```ps1
|
||||
# - toolsets: "" (p), "v140" (MSVC 2015), "v141" (MSVC 2017), "v141_xp" (XP support), "v142" (MSVC 2019), etc
|
||||
# - sdks: "" (default), "7.0" (Win7 SDK), "8.1" (Win8 SDK), "10.0" (Win10 SDK), etc
|
||||
$toolset = "142"
|
||||
$sdk = "10.0"
|
||||
```
|
||||
It's also possible to call MSBuild and pass those values from the CMD, see foobar section for an example.
|
||||
|
||||
Once finished resulting binaries are in the *./Release* folder. Remember you need to copy extra `.dll` to run them (see [USAGE.md](USAGE.md)).
|
||||
|
||||
**For GCC/CLang**: there are basic Makefiles that work like usual with *make* (like `make vgmstream_cli EXTRA_CFLAGS="-DVGM_DEBUG_OUTPUT`). Artifacts are usually in their subdir (*./cli*, *./winamp*, etc).
|
||||
|
||||
On **Windows** this compiles with extra libs enabled by default.
|
||||
|
||||
On **Linux** there is no fancy autodetection (try CMake or autotools for that), so you need to make sure libs are in your system and pass flags to enable them manually (install/compile libs then `make vgmstream_cli VGM_VORBIS=1 ...`). Check or run `make-build.sh` for a basic example that builds CLI and vgmstream123 with most libs enabled for a Ubuntu-style distro (if you get errors on your system just tweak or comment out offending parts).
|
||||
|
||||
**Linux** example:
|
||||
```sh
|
||||
sudo apt-get install -y git
|
||||
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
# in case they weren't set
|
||||
chmod +x version-get.sh version-make.sh make-build.sh
|
||||
|
||||
# warning: installs stuff, check all "apt install"
|
||||
./make-build.sh
|
||||
```
|
||||
|
||||
### autotools (builds)
|
||||
Autogenerated *make* scripts, used by some modules (mainly Audacious for **Linux**, and external libs).
|
||||
|
||||
For **Windows** you must include GCC, and Linux's sh tool in some form in PATH. Simplest would be installing *MinGW-w64* for `gcc.exe` (and related tools), and *Git* for `sh.exe`, and making PATH point their bin dir.
|
||||
- ex. `C:\mingw\i686-8.1.0-release-win32-sjlj-rt_v6-rev0\mingw32\bin` and `C:\Git\usr\bin`
|
||||
- Both must be installed/copied in a dir without spaces (with spaces autoconf seemingly works but creates buggy files)
|
||||
- If you don't have Git, try compiled GNU tools for Windows (http://gnuwin32.sourceforge.net/packages.html)
|
||||
|
||||
A trick on **Windows** is that you can temporary alter PATH variable in `.bat` scripts (PATH is used to call programs in Windows without having to write full path to .exe)
|
||||
```bat
|
||||
set PATH=%PATH%;C:\mingw\i686-8.1.0-release-win32-sjlj-rt_v6-rev0\mingw32\bin
|
||||
set PATH=%PATH%;C:\Git\usr\bin
|
||||
gcc.exe (...)
|
||||
```
|
||||
|
||||
For **Linux**, GCC/make/autotools should be included already, or install with a package manager, also depends on *Make*.
|
||||
```sh
|
||||
sudo apt-get install gcc g++ make autoconf automake libtool
|
||||
```
|
||||
|
||||
Typical usage involves creating Makefiles with `bootstrap` and `configure`, `make` (with the correct makefile) to compile, and `make install` to copy results. This varies slightly depending on module/lib (explained later).
|
||||
```sh
|
||||
./bootstrap
|
||||
./configure
|
||||
make -f Makefile.autotools
|
||||
sudo make -f Makefile.autotools install
|
||||
```
|
||||
|
||||
External libs using autotools can be compiled on **Windows** too:
|
||||
```bat
|
||||
sh.exe ./bootstrap
|
||||
sh.exe ./configure
|
||||
mingw32-make.exe -f Makefile.autotools
|
||||
mingw32-make.exe -f Makefile.autotools install
|
||||
```
|
||||
Also for older libs, call `sh.exe ./configure` with either `--build=mingw32`, `--host=mingw32` or `--target-os=mingw32` (varies) for older configure. You may also need to use this command so that `.dll` files are correctly generated:
|
||||
```bat
|
||||
mingw32-make.exe -f Makefile.autotools LDFLAGS="-no-undefined -static-libgcc" MAKE=mingw32-make.exe
|
||||
```
|
||||
|
||||
|
||||
### GCC / Make (compiler)
|
||||
Common C compiler, most development is done with this.
|
||||
|
||||
On **Windows** you need one of these somewhere in PATH:
|
||||
- MinGW-w64 (32bit version): https://sourceforge.net/projects/mingw-w64/
|
||||
- Use this for easier standalone executables
|
||||
- [Latest online MinGW installer](https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/installer/mingw-w64-install.exe/download) with any config should work (for example: gcc-8.1.0, i686, win32, sjlj).
|
||||
- Or download and unzip the [portable MinGW package](https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/8.1.0/threads-win32/sjlj/i686-8.1.0-release-win32-sjlj-rt_v6-rev0.7z/download)
|
||||
- MSYS2 with the MinGW-w64_shell (32bit) package: https://msys2.github.io/
|
||||
- Resulting binaries may depend on `msys*.dll`.
|
||||
|
||||
On **Linux** it should be included by default in the distribution, or can be easily installed using the distro's package manager (for example `sudo apt-get install gcc g++ make`).
|
||||
|
||||
On **macOS** may be installed with a package manager like *Homebrew*, but using *Clang* is probably easier.
|
||||
|
||||
Any versions that are not too ancient should work, since vgmstream uses standard C. GCC usually comes with *Make*, a program that can be used to build vgmstream.
|
||||
|
||||
### Microsoft's Visual C++ (MSVC) / Visual Studio / MSBuild (compiler)
|
||||
Alt C compiler (**Windows** only), auto-generated builds for Windows use this. Bundled in:
|
||||
- Visual Studio (2015/2017/2019/latest): https://www.visualstudio.com/downloads/
|
||||
|
||||
Visual Studio Community (free) should work, but you may need to register after a trial period. Even after trial you can still use *MSBuild*, command-line tool that actually does all the building, calling the *MSVC* compiler (Visual Studio itself is just an IDE for development and not actually needed).
|
||||
|
||||
Instead of the full (usually huge) Visual Studio, you can also get "Build Tools for Visual Studio", variation that only installs *MSBuild* and necessary files without the IDE. Usually found in the above link, under "Tools for Visual Studio" (or google as MS's links tend to move around).
|
||||
|
||||
When installing check the "Desktop development with C++" group, and optionally select "MFC support" and "ATL support" sub-options to build foobar2000 plugin (you can modify that or re-install IDE later, by running installed "Visual Studio Installer"). You could include MSVC v141 (2017) compatibility too just in case, since it's mainly tested with that.
|
||||
|
||||
Older versions of MSVC (2010 and earlier) have limited C support and may not work with latest commits, while reportedly beta/new versions aren't always very stable. Also, only projects (`.vcxproj`) for VS2015+ are included (CMake may be able to generate older `.vcproj` if you really need them). Some very odd issues affecting MSVC only have been found and fixed before. Keep in mind all of this if you run into problems.
|
||||
|
||||
### Clang (compiler)
|
||||
Alt C compiler, reportedly works fine on **macOS** and may used as a replacement of GCC without issues.
|
||||
- https://releases.llvm.org/download.html
|
||||
|
||||
Should be usable on **Linux** and possibly **Windows** with CMake. For default Makefiles may need to set compiler vars appropriately (`CC=clang`, `AR=llvm-ar` and so on).
|
||||
|
||||
|
||||
### Emscripten (compiler)
|
||||
It's possible to build vgmstream components with Emscripten for in-browser support.
|
||||
|
||||
Follow Emscripten installation instructions:
|
||||
- https://emscripten.org/docs/getting_started/downloads.html
|
||||
- https://emscripten.org/docs/compiling/Building-Projects.html#building-projects
|
||||
|
||||
Though basically:
|
||||
```sh
|
||||
git clone https://github.com/emscripten-core/emsdk
|
||||
cd emsdk
|
||||
./emsdk install latest
|
||||
./emsdk activate latest
|
||||
source ./emsdk_env.sh
|
||||
```
|
||||
|
||||
Then you should be able to build it on **Linux** (**Windows** would be possible too, but it has some issues at the moment), for example with CMake:
|
||||
```sh
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
|
||||
mkdir -p embuild
|
||||
cd embuild
|
||||
emcmake cmake ..
|
||||
make
|
||||
```
|
||||
You can compile faster using `make -j 5` instead of the last `make` command (replace `5` with the number of cores your CPU has plus one), but please note that, with multiple jobs, in case any issues occur the output will become useless.
|
||||
|
||||
The output files `vgmstream-cli.wasm` and `vgmstream-cli.js` will be located in the `embuild/cli` directory.
|
||||
|
||||
Or with the base makefiles (the output may need to be renamed to .js):
|
||||
```sh
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
make vgmstream-cli CC=emcc AR=emar strip=echo
|
||||
```
|
||||
|
||||
Load `vgmstream-cli.js` in a web page, you will be able to call the `callMain()` function from the browser developer console. Parameters to vgmstream can be passed in an array: `callMain(["-i", "input_file.pcm"])`. Files can be accessed through Emscripten [File System API](https://emscripten.org/docs/api_reference/Filesystem-API.html) (`FS`).
|
||||
|
||||
|
||||
### Git (extras)
|
||||
Code version control for development. Optional, used to auto-generate version numbers:
|
||||
- https://git-scm.com/download
|
||||
|
||||
Remember Git can only be used if you clone the vgmstream repo (not with `.zip` sources).
|
||||
|
||||
On **Windows**, Git also comes with typical Linux utils (in the usr\bin dir), that can help when compiling some extra components.
|
||||
|
||||
### Extra libs (extras)
|
||||
Optional codec. See *External libraries* for full info.
|
||||
|
||||
On **Windows** most libs are pre-compiled and included to simplify building (since they can be quite involved to compile).
|
||||
|
||||
On **Linux** you usually need dev packages of each (for example `libao-dev` for vgmstream123, `libvorbis-dev` for Vorbis, and so on) and they should be picked by CMake/autotool scripts.
|
||||
|
||||
With no extra libs (or only some) enabled vgmstream works fine, but some advanced formats/codecs won't play. See *External libraries* for info about those extra codecs.
|
||||
|
||||
|
||||
## Compiling modules
|
||||
|
||||
### CLI (test.exe/vgmstream-cli) / Winamp plugin (in_vgmstream) / XMPlay plugin (xmp-vgmstream)
|
||||
|
||||
**With GCC/Clang**: there are various ways to build it, each with some differences; you probably want CMake described below.
|
||||
|
||||
Simplest way is using the *./Makefile* in the root folder, see inside for options. For compilation flags check the *Makefile* in each folder. You may need to manually rebuild if you change a *.h* file (`make clean`). On **Windows** this will build with external libs enabled, but **Linux** can't at the moment.
|
||||
|
||||
Also, on **Linux** you can't build *in_vgmstream* and *xmp-vgmstream* (given they are Windows DLLs...). Makefiles have been used in the past to cross-compile from Linux with MingW headers though, but can't generate native Win code at the moment (should be fixable with some effort).
|
||||
|
||||
*Autotools* should build and install it as `vgmstream-cli`, this is explained in detail in the Audacious section. It enables (some) extra codecs. Some Linux distributions like **Arch Linux** include pre-patched vgmstream with most libraries, you may want that instead:
|
||||
- https://aur.archlinux.org/packages/vgmstream-git/
|
||||
|
||||
If you use **macOS or Linux**, there is a *Homebrew* script that may automate the process (uses CMake):
|
||||
- https://formulae.brew.sh/formula/vgmstream
|
||||
|
||||
You may try CMake instead as it may be simpler and handle libs better. See the build steps in the [Cmake section](#cmake-builds). Some older distros may not work though (CMake version needs to recognize FILTER command). You may also need to install resulting artifacts manually. Check the *CMAKE.md* doc for some extra info too.
|
||||
|
||||
**Windows** CMD .bat example (with some debugging on):
|
||||
```bat
|
||||
prompt $P$G$_$S
|
||||
set PATH=C:\Program Files (x86)\Git\usr\bin;%PATH%
|
||||
set PATH=C:\Program Files (x86)\mingw-w64\i686-5.4.0-win32-sjlj-rt_v5-rev0\mingw32\bin;%PATH%
|
||||
@ -191,8 +257,8 @@ If you get build errors, remember you need to adjust compiler/SDK in the `.sln`.
|
||||
|
||||
CMake can also be used instead to create project files (no particular benefit).
|
||||
|
||||
#### notes
|
||||
While the official name for the CLI tool is `vgmstream-cli`, `test.exe` is used on Windows for historical reasons. If you want to reuse it for your own project it's probably better renaming to `vgmstream-cli.exe`.
|
||||
#### Notes
|
||||
While the official name for the CLI tool is `vgmstream-cli`, on **Windows**, `test.exe` is used instead for historical reasons. If you want to reuse it for your project, it's probably better to rename it to `vgmstream-cli.exe`.
|
||||
|
||||
|
||||
### foobar2000 plugin (foo\_input\_vgmstream)
|
||||
@ -214,8 +280,8 @@ In theory any foobar SDK should work, but there may be issues when using version
|
||||
|
||||
You can also manually use the command line to compile with MSBuild, if you don't want to touch the `.vcxproj` files, register VS after trial, get PowerShell dependencies for the build script, or only have VC++/MSBuild tools.
|
||||
|
||||
Windows CMD example for foobar2000 (manual build):
|
||||
```
|
||||
**Windows** CMD example for foobar2000 (manual build):
|
||||
```bat
|
||||
prompt $P$G$_$S
|
||||
|
||||
REM MSVC ~2015
|
||||
@ -251,32 +317,17 @@ The plugin needs Audacious 3.5 or higher. New Audacious releases can break plugi
|
||||
|
||||
CMake should handle all correctly, while when using autotools, libvorbis/libmpg123/libspeex will be used if found, while FFmpeg and other external libraries aren't enabled at the moment, thus some formats won't work (build scripts need to be fixed).
|
||||
|
||||
Windows builds aren't supported at the moment (should be possible but there are complex dependency chains).
|
||||
**Windows** builds aren't supported at the moment (should be possible but there are complex dependency chains).
|
||||
|
||||
If you get errors during the build phase we probably forgot some `#ifdef` needed for Audacious, notify and should be quickly fixed.
|
||||
If you get errors during the build phase, we probably forgot some `#ifdef` needed for Audacious, please [notify us](https://github.com/vgmstream/vgmstream/issues) if that happens.
|
||||
|
||||
Take note of other plugins stealing extensions (see README). To change Audacious's default priority for vgmstream you can make with CFLAG `AUDACIOUS_VGMSTREAM_PRIORITY n` (where `N` is a number where 10=lowest)
|
||||
Take note of other plugins stealing extensions (see [USAGE.md](USAGE.md#common-and-unknown-extensions)). To change Audacious's default priority for vgmstream you can make with CFLAG `AUDACIOUS_VGMSTREAM_PRIORITY n` (where `N` is a number where 10=lowest)
|
||||
|
||||
|
||||
You can try building with CMake. Some older distros may not work though (CMake version needs to recognize FILTER command), and may need to install resulting artifacts manually (check ./audacious dir).
|
||||
```
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y gcc g++ make build-essential git
|
||||
sudo apt-get install -y libmpg123-dev libvorbis-dev libspeex-dev
|
||||
sudo apt-get install -y libavformat-dev libavcodec-dev libavutil-dev libswresample-dev
|
||||
sudo apt-get install -y libao-dev audacious-dev
|
||||
sudo apt-get install -y cmake
|
||||
You can try building with CMake. See the build steps in the [Cmake section](#cmake-builds). Some older distros may not work though (CMake version needs to recognize FILTER command), and may need to install resulting artifacts manually (check `./audacious` dir).
|
||||
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
|
||||
# for older versions try "cmake ." instead
|
||||
cmake -S . -B build
|
||||
make
|
||||
```
|
||||
|
||||
Instead of CMake you can use autotools. Terminal example, assuming a Ubuntu-based Linux distribution:
|
||||
```
|
||||
Instead of CMake you can use autotools. Terminal example, assuming a **Ubuntu-based Linux** distribution:
|
||||
```sh
|
||||
# build setup
|
||||
|
||||
# default requirements
|
||||
@ -294,8 +345,8 @@ sudo apt-get install libao-dev
|
||||
|
||||
# check Audacious version >= 3.5
|
||||
pkg-config --modversion audacious
|
||||
```
|
||||
```
|
||||
|
||||
|
||||
# base vgmstream build
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
@ -319,7 +370,7 @@ audacious -V
|
||||
# in the terminal log, then go to menu services > plugins > input tab and check
|
||||
# vgmstream is there (you can start audacious normally next time)
|
||||
```
|
||||
```
|
||||
```sh
|
||||
# uninstall if needed
|
||||
sudo make -f Makefile.autotools uninstall
|
||||
|
||||
@ -335,7 +386,7 @@ To update vgmstream it's probably easiest to remove the `vgmstream` folder and s
|
||||
### vgmstream123 player
|
||||
Should be buildable with Autotools/CMake by following the same steps as listen in the Audacious section (requires *libao-dev*).
|
||||
|
||||
Windows builds are possible with `libao.dll` and `libao` includes (found elsewhere) through the `Makefile`, but some features are disabled.
|
||||
**Windows** builds are possible with `libao.dll` and `libao` includes (found elsewhere) through the `Makefile`, but some features are disabled.
|
||||
|
||||
*libao* is licensed under the GPL v2 or later.
|
||||
|
||||
@ -343,8 +394,16 @@ Windows builds are possible with `libao.dll` and `libao` includes (found elsewhe
|
||||
## Shared lib
|
||||
Currently there isn't an official way to make vgmstream a shared lib (`.so`/`.dll`), but it can be achieved with some effort.
|
||||
|
||||
For example with the basic makefiles:
|
||||
For example with CMake (outputs in `build/src/libvgmstream.so`):
|
||||
```sh
|
||||
mkdir -p build
|
||||
cd build
|
||||
cmake ..
|
||||
make libvgmstream_shared
|
||||
```
|
||||
|
||||
Or with the basic makefiles:
|
||||
```sh
|
||||
# build all of the intermediates with relocatable code
|
||||
# *note*: quick hack with performance penalty, needs better dependency rules
|
||||
make vgmstream_cli EXTRA_CFLAGS=-fPIC
|
||||
@ -362,41 +421,6 @@ For integration and "API" usage, easiest would be checking how `vgmstream_cli.c`
|
||||
A cleaner API/.h and build methods is planned for the future (low priority though).
|
||||
|
||||
|
||||
# emscripten / wasm
|
||||
It's possible to build vgmstream components with emscripten (in-browser support).
|
||||
|
||||
Follow emscripten's installation instructions:
|
||||
- https://emscripten.org/docs/getting_started/downloads.html
|
||||
- https://emscripten.org/docs/compiling/Building-Projects.html#building-projects
|
||||
|
||||
Though basically:
|
||||
```
|
||||
git clone https://github.com/emscripten-core/emsdk
|
||||
cd emsdk
|
||||
./emsdk install latest
|
||||
./emsdk activate latest
|
||||
source ./emsdk_env.sh
|
||||
```
|
||||
|
||||
Then you should be able to build it on Linux (Windows would be possible too, but it has some issues at the moment), for example:
|
||||
```
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
mkdir -p embuild && cd embuild
|
||||
|
||||
emcmake cmake -S .. -B .
|
||||
emmake make
|
||||
```
|
||||
The output files `vgmstream-cli.wasm` and `vgmstream-cli.js` will be located in the `embuild/cli` directory.
|
||||
|
||||
Or with the base makefiles (may need to rename output to .js ATM):
|
||||
```
|
||||
git clone https://github.com/vgmstream/vgmstream
|
||||
cd vgmstream
|
||||
make vgmstream-cli CC=emcc AR=emar strip=echo
|
||||
```
|
||||
|
||||
|
||||
## External libraries
|
||||
Support for some codecs is done with external libs, instead of copying their code in vgmstream. There are various reasons for this:
|
||||
- each lib may have complex or conflicting ways to compile that aren't simple to replicate
|
||||
@ -407,9 +431,9 @@ Support for some codecs is done with external libs, instead of copying their cod
|
||||
|
||||
They are compiled in their own sources, and the resulting binary is linked by vgmstream using a few of their symbols.
|
||||
|
||||
Currently repo contains pre-compiled external libraries for Windows (32-bit Windows DLLs), while other systems link to system libraries. Ideally vgmstream could use libs compiled as static code (thus eliminating the need of DLLs), but involves a bunch of changes.
|
||||
Currently repo contains pre-compiled external libraries for **Windows** (32-bit Windows DLLs), while other systems link to system libraries. Ideally vgmstream could use libs compiled as static code (thus eliminating the need of DLLs), but involves a bunch of changes.
|
||||
|
||||
Below is a quick explanation of each library and how to compile binaries from them (for Windows). Unless mentioned, their latest version should be ok to use, though included DLLs may be a bit older.
|
||||
Below is a quick explanation of each library and how to compile binaries from them (for **Windows**). Unless mentioned, their latest version should be ok to use, though included DLLs may be a bit older.
|
||||
|
||||
MSVC needs a .lib helper to link .dll files, but libs below usually only create .dll (and maybe .def). Instead, those .lib are automatically generated during build step in `ext_libs.vcxproj` from .dll+.def, using lib.exe tool.
|
||||
|
||||
@ -452,11 +476,11 @@ Adds support for multiple codecs: ATRAC3 (`.at3`), ATRAC3plus (`.at3`), XMA1/2 (
|
||||
- lib: `-lavcodec -lavformat -lavutil -lswresample`
|
||||
- primarily licensed under the LGPL v2.1 or later, with portions licensed under the GPL v2
|
||||
|
||||
vgmstream's FFmpeg builds for Windows remove many unnecessary parts of FFmpeg to trim down its gigantic size, and are also built with the "vgmstream-" prefix to avoid clashing with other plugins. Current options can be seen in `ffmpeg_options.txt`. Linux usually links to the system's FFmpeg without issues.
|
||||
vgmstream's FFmpeg builds for **Windows** and static builds for **Linux** remove many unnecessary parts of FFmpeg to trim down its gigantic size, and, on Windows, are also built with the "vgmstream-" prefix to avoid clashing with other plugins. Current options can be seen in `ffmpeg_options.txt`. Shared **Linux** builds usually link to system FFmpeg without issues.
|
||||
|
||||
Note that the options above use *libopus*, but you can use FFmpeg's *Opus* by removing `--enable-libopus` and changing `--enable-decoder`'s `libopus` to `opus`. libopus is preferable since FFmpeg's Opus decoding is buggy in some files.
|
||||
|
||||
For GCC simply use autotools (configure, make, make install), passing to `configure` the above options.
|
||||
For GCC simply use [autotools](#autotools-builds), passing to `./configure` the above options.
|
||||
|
||||
For MSCV it can be done through a helper: https://github.com/jb-alvarado/media-autobuild_suite
|
||||
|
||||
@ -490,7 +514,7 @@ FSB uses two incompatible, older libcelt versions. Both libraries export the sam
|
||||
|
||||
To compile we'll use autotools with GCC preprocessor renaming:
|
||||
- in the celt-0.6.1 dir:
|
||||
```
|
||||
```bat
|
||||
# creates Makefiles with Automake
|
||||
sh.exe ./configure --build=mingw32 --prefix=/c/celt0.6.1/bin/ --exec-prefix=/c/celt-0.6.1/bin/
|
||||
|
||||
@ -500,7 +524,7 @@ To compile we'll use autotools with GCC preprocessor renaming:
|
||||
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"
|
||||
```
|
||||
- in the celt-0.11.0 dir:
|
||||
```
|
||||
```bat
|
||||
# creates Makefiles with Automake
|
||||
sh.exe ./configure --build=mingw32 --prefix=/c/celt-0.11.0/bin/ --exec-prefix=/c/celt-0.11.0/bin/
|
||||
|
||||
@ -513,7 +537,7 @@ 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**, an option is using AUR's scripts (https://aur.archlinux.org/packages/vgmstream-git/) that similarly patch celt libs in PKGBUILD.
|
||||
|
||||
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`).
|
||||
|
||||
@ -527,10 +551,10 @@ Adds support for Speex (inside custom containers), used in a few *EA* formats (`
|
||||
|
||||
Should be buildable with MSVC (in /win32 dir are .sln files, but not up to date and may need to convert .vcproj to vcxproj) or autotools (use `autogen.sh`, or script below).
|
||||
|
||||
You can also find a release on Github (https://github.com/xiph/speex/releases/tag/Speex-1.2.0). It has newer timestamps and some different helper files vs Xiph's release, but actual lib should be the same. Notably, Github's release *needs* `autogen.sh` that calls `autoreconf` to generate a base `configure` script, while Xiph's pre-includes `configure`. Since getting autoreconf working on Windows can be quite involved, Xiph's release is recommended on that platform.
|
||||
You can also find a release on Github (https://github.com/xiph/speex/releases/tag/Speex-1.2.0). It has newer timestamps and some different helper files vs Xiph's release, but actual lib should be the same. Notably, Github's release *needs* `autogen.sh` that calls `autoreconf` to generate a base `configure` script, while Xiph's pre-includes `configure`. Since getting autoreconf working on **Windows** can be quite involved, Xiph's release is recommended on that platform.
|
||||
|
||||
Windows CMD example:
|
||||
```
|
||||
**Windows** CMD example:
|
||||
```bat
|
||||
set PATH=%PATH%;C:\mingw\i686-8.1.0-release-win32-sjlj-rt_v6-rev0\mingw32\bin
|
||||
set PATH=%PATH%;C:\Git\usr\bin
|
||||
|
||||
|
||||
25
doc/CMAKE.md
25
doc/CMAKE.md
@ -29,7 +29,9 @@ See [BUILD.md](BUILD.md)'s *Compilation requirements* for more info about variou
|
||||
|
||||
It is recommended to do out-of-source builds as opposed to in-source builds. Out-of-source builds have been tested to work, while in-source builds have not been tested at all.
|
||||
|
||||
***NOTE:*** The CMake scripts attempt to collect all the source files are configuration time. If you are following vgmstream development through git or adding your own source files, you **MUST** re-run CMake manually to regenerate the files. Failure to do so can result in either missing functionality or compile errors.
|
||||
Create a directory called `build` and run cmake commands from there.
|
||||
|
||||
***NOTE:*** The CMake scripts attempt to collect all the source files at configuration time. If you are following vgmstream development through git or adding your own source files, you **MUST** re-run CMake manually to regenerate the files. Failure to do so can result in either missing functionality or compile errors.
|
||||
|
||||
First you will need to run CMake to generate the build setup. You can use either the CMake GUI or run CMake from the command line.
|
||||
|
||||
@ -71,7 +73,7 @@ cd vgmstream
|
||||
cmake -DUSE_FFMPEG=ON -DBUILD_AUDACIOUS=OFF -S . -B build
|
||||
```
|
||||
|
||||
You may need to install appropriate packages first (see [BUILD.md)(BUILD.md) for more info), for example:
|
||||
You may need to install appropriate packages first (see [BUILD.md](BUILD.md) for more info), for example:
|
||||
```
|
||||
sudo apt-get update
|
||||
# basic compilation
|
||||
@ -88,6 +90,10 @@ sudo apt-get install -y libjansson-dev
|
||||
sudo apt-get install -y yasm libopus-dev
|
||||
# actual cmake
|
||||
sudo apt-get install -y cmake
|
||||
|
||||
mkdir -p build
|
||||
cd build
|
||||
cmake ..
|
||||
```
|
||||
|
||||
Once you have run the command, as long as there are no errors, you should see the following at the bottom of the window:
|
||||
@ -112,6 +118,8 @@ If not using a project-based GUI, then you will also need to set what build type
|
||||
- **RelWithDebInfo**: Like Release but with debugging information included
|
||||
- **MinSizeRel**: Like Release but aims for minimum size
|
||||
|
||||
For example: `cmake .. -DCMAKE_BUILD_TYPE=Release`
|
||||
|
||||
#### Library Options
|
||||
|
||||
All of these options are of type BOOL and can be set to either `ON` or `OFF`. Most of the details on these libraries can be found in the [External Libraries section of BUILD.md](BUILD.md#external-libraries).
|
||||
@ -125,19 +133,19 @@ All of these options are of type BOOL and can be set to either `ON` or `OFF`. Mo
|
||||
- **USE_ATRAC9**: Chooses if you wish to use LibAtrac9 for support of ATRAC9. The default is `ON`.
|
||||
- **USE_SPEEX**: Chooses if you wish to use libspeex for support of SPEEX. The default is `ON`.
|
||||
|
||||
The following option is currently only available for Windows:
|
||||
The following option is currently only available for **Windows**:
|
||||
|
||||
- **USE_CELT**: Chooses if you wish to use libcelt for support of FSB CELT versions 0.6.1 and 0.11.0. The default is `ON`.
|
||||
|
||||
The following option is only available for *nix-based OSes:
|
||||
The following option is only available for **\*nix-based OSes**:
|
||||
|
||||
- **USE_JANSSON**: Chooses if you wish to use libjansson for support of JSON dumping capabilities. The default is `ON`.
|
||||
|
||||
#### Build Options
|
||||
|
||||
All of these options are of type BOOL and can be set to either `ON` or `OFF`.
|
||||
All of these options are of type BOOL and can be set to either `ON` or `OFF`. Example usage: `cmake .. -DBUILD_CLI=ON`
|
||||
|
||||
- **BUILD_CLI**: Chooses if you wish to build the vgmstream CLI program (as well as vgmstream123 on *nix-based OSes). The default is `ON`.
|
||||
- **BUILD_CLI**: Chooses if you wish to build the vgmstream CLI program. The default is `ON`.
|
||||
|
||||
The following options are only available for Windows:
|
||||
|
||||
@ -153,7 +161,7 @@ The following option is only available for *nix-based OSes:
|
||||
|
||||
#### Paths
|
||||
|
||||
All of these paths are of type PATH.
|
||||
These options are for setting the path to the library source code. The CMake script will then configure and build each library. All of these paths are of type PATH. Example usage: `cmake .. -DMPEG_PATH=~/source_code/mpg123`
|
||||
|
||||
If FDK-AAC/QAAC support is enabled, the following paths are required (with more details in the foobar2000 plugin section of [BUILD.md](BUILD.md)):
|
||||
|
||||
@ -164,9 +172,10 @@ If FDK-AAC/QAAC support is enabled, the following paths are required (with more
|
||||
- **FFMPEG_PATH**: The path to the FFmpeg source directory. It can be obtained at https://git.ffmpeg.org/ffmpeg.git If not set and static building is enabled, this will be downloaded automatically.
|
||||
- **G719_PATH**: The path to the G.719 decoder library. It can be obtained at https://github.com/kode54/libg719_decode If not set, it is downloaded automatically on Linux.
|
||||
- **ATRAC9_PATH**: The path to the Atrac9 library. It can be obtained at https://github.com/Thealexbarney/LibAtrac9 If not set, it is downloaded automatically on Linux.
|
||||
- **SPEEX_PATH**: The path to the SPEEX library. It can be obtained at https://gitlab.xiph.org/xiph/speex If not set, it is downloaded automatically when building with Emscripten.
|
||||
- **LIBAO_PATH**: The path to the AO library. If static building is enabled and you chose to build the vgmstream123 player, providing this path is required. It is not recommended to use.
|
||||
|
||||
The CLI/vgmstream123 programs are normally installed to `CMAKE_INSTALL_PREFIX`, changing this will change where those are installed.
|
||||
The CLI/vgmstream123 programs are normally installed to `CMAKE_INSTALL_PREFIX`, changing this will change where those are installed: `cmake .. -DCMAKE_INSTALL_PREFIX=/custom/path`
|
||||
|
||||
If building the foobar2000 component, the following paths are required:
|
||||
|
||||
|
||||
332
doc/FORMATS.md
Normal file
332
doc/FORMATS.md
Normal file
@ -0,0 +1,332 @@
|
||||
## Supported file types
|
||||
As manakoAT likes to say, the extension doesn't really mean anything, but it's
|
||||
the most obvious way to identify files.
|
||||
|
||||
This list is not complete and many other files are supported.
|
||||
|
||||
- PS2/PSX ADPCM:
|
||||
- .ads/.ss2
|
||||
- .ass
|
||||
- .ast
|
||||
- .bg00
|
||||
- .bmdx
|
||||
- .ccc
|
||||
- .cnk
|
||||
- .dxh
|
||||
- .enth
|
||||
- .fag
|
||||
- .filp
|
||||
- .gcm
|
||||
- .gms
|
||||
- .hgc1
|
||||
- .ikm
|
||||
- .ild
|
||||
- .ivb
|
||||
- .joe
|
||||
- .kces
|
||||
- .khv
|
||||
- .leg
|
||||
- .mcg
|
||||
- .mib, .mi4 (w/ or w/o .mih)
|
||||
- .mic
|
||||
- .mihb (merged mih+mib)
|
||||
- .msa
|
||||
- .msvp
|
||||
- .musc
|
||||
- .npsf
|
||||
- .pnb
|
||||
- .psh
|
||||
- .rkv
|
||||
- .rnd
|
||||
- .rstm
|
||||
- .rws
|
||||
- .rxw
|
||||
- .snd
|
||||
- .sfs
|
||||
- .sl3
|
||||
- .smpl (w/ bad flags)
|
||||
- .ster
|
||||
- .str+.sth
|
||||
- .str (MGAV blocked)
|
||||
- .sts
|
||||
- .svag
|
||||
- .svs
|
||||
- .tec (w/ bad flags)
|
||||
- .tk5 (w/ bad flags)
|
||||
- .vas
|
||||
- .vag
|
||||
- .vgs (w/ bad flags)
|
||||
- .vig
|
||||
- .vpk
|
||||
- .vs
|
||||
- .vsf
|
||||
- .wp2
|
||||
- .xa2
|
||||
- .xa30
|
||||
- .xwb+xwh
|
||||
- GC/Wii/3DS DSP ADPCM:
|
||||
- .aaap
|
||||
- .agsc
|
||||
- .asr
|
||||
- .bns
|
||||
- .bo2
|
||||
- .capdsp
|
||||
- .cfn
|
||||
- .ddsp
|
||||
- .dsp
|
||||
- standard, optional dual file stereo
|
||||
- RS03
|
||||
- Cstr
|
||||
- _lr.dsp
|
||||
- MPDS
|
||||
- .gca
|
||||
- .gcm
|
||||
- .gsp+.gsp
|
||||
- .hps
|
||||
- .idsp
|
||||
- .ish+.isd
|
||||
- .lps
|
||||
- .mca
|
||||
- .mpdsp
|
||||
- .mss
|
||||
- .mus (not quite right)
|
||||
- .ndp
|
||||
- .pdt
|
||||
- .sdt
|
||||
- .smp
|
||||
- .sns
|
||||
- .spt+.spd
|
||||
- .ssm
|
||||
- .stm/.dsp
|
||||
- .str
|
||||
- .str+.sth
|
||||
- .sts
|
||||
- .swd
|
||||
- .thp, .dsp
|
||||
- .tydsp
|
||||
- .vjdsp
|
||||
- .waa, .wac, .wad, .wam
|
||||
- .was
|
||||
- .wsd
|
||||
- .wsi
|
||||
- .ydsp
|
||||
- .ymf
|
||||
- .zwdsp
|
||||
- PCM:
|
||||
- .aiff (8 bit, 16 bit)
|
||||
- .asd (16 bit)
|
||||
- .baka (16 bit)
|
||||
- .bh2pcm (16 bit)
|
||||
- .dmsg (16 bit)
|
||||
- .gcsw (16 bit)
|
||||
- .gcw (16 bit)
|
||||
- .his (8 bit)
|
||||
- .int (16 bit)
|
||||
- .pcm (8 bit, 16 bit)
|
||||
- .kraw (16 bit)
|
||||
- .raw (16 bit)
|
||||
- .rwx (16 bit)
|
||||
- .sap (16 bit)
|
||||
- .snd (16 bit)
|
||||
- .sps (16 bit)
|
||||
- .str (16 bit)
|
||||
- .xss (16 bit)
|
||||
- .voi (16 bit)
|
||||
- .wb (16 bit)
|
||||
- .zsd (8 bit)
|
||||
- Xbox IMA ADPCM:
|
||||
- .matx
|
||||
- .wavm
|
||||
- .wvs
|
||||
- .xmu
|
||||
- .xvas
|
||||
- .xwav
|
||||
- Yamaha AICA ADPCM:
|
||||
- .adpcm
|
||||
- .dcs+.dcsw
|
||||
- .str
|
||||
- .spsd
|
||||
- IMA ADPCM:
|
||||
- .bar (IMA ADPCM)
|
||||
- .pcm/dvi (DVI IMA ADPCM)
|
||||
- .hwas (IMA ADPCM)
|
||||
- .dvi/idvi (DVI IMA ADPCM)
|
||||
- .ivaud (IMA ADPCM)
|
||||
- .myspd (IMA ADPCM)
|
||||
- .strm (IMA ADPCM)
|
||||
- multi:
|
||||
- .aifc (SDX2 DPCM, DVI IMA ADPCM)
|
||||
- .asf/as4 (8/16 bit PCM, DVI IMA ADPCM)
|
||||
- .ast (GC AFC ADPCM, 16 bit PCM)
|
||||
- .aud (IMA ADPCM, WS DPCM)
|
||||
- .aus (PSX ADPCM, Xbox IMA ADPCM)
|
||||
- .brstm (GC DSP ADPCM, 8/16 bit PCM)
|
||||
- .emff (PSX APDCM, GC DSP ADPCM)
|
||||
- .fsb/wii (PSX ADPCM, GC DSP ADPCM, Xbox IMA ADPCM, MPEG audio, FSB Vorbis, MS XMA)
|
||||
- .msf (PCM, PSX ADPCM, ATRAC3, MP3)
|
||||
- .musx (PSX ADPCM, Xbox IMA ADPCM, DAT4 IMA ADPCM)
|
||||
- .nwa (16 bit PCM, NWA DPCM)
|
||||
- .p3d (Radical ADPCM, Radical MP3, XMA2)
|
||||
- .psw (PSX ADPCM, GC DSP ADPCM)
|
||||
- .rwar, .rwav (GC DSP ADPCM, 8/16 bit PCM)
|
||||
- .rws (PSX ADPCM, XBOX IMA ADPCM, GC DSP ADPCM, 16 bit PCM)
|
||||
- .rwsd (GC DSP ADPCM, 8/16 bit PCM)
|
||||
- .rsd (PSX ADPCM, 16 bit PCM, GC DSP ADPCM, Xbox IMA ADPCM, Radical ADPCM)
|
||||
- .rrds (NDS IMA ADPCM)
|
||||
- .sad (GC DSP ADPCM, NDS IMA ADPCM, Procyon Studios NDS ADPCM)
|
||||
- .sgd/sgb+sgh/sgx (PSX ADPCM, ATRAC3plus, AC3)
|
||||
- .seg (Xbox IMA ADPCM, PS2 ADPCM)
|
||||
- .sng/asf/str/eam/aud (8/16 bit PCM, EA-XA ADPCM, PSX ADPCM, GC DSP ADPCM, XBOX IMA ADPCM, MPEG audio, EALayer3)
|
||||
- .strm (NDS IMA ADPCM, 8/16 bit PCM)
|
||||
- .sb0..7 (Ubi IMA ADPCM, GC DSP ADPCM, PSX ADPCM, Xbox IMA ADPCM, ATRAC3)
|
||||
- .swav (NDS IMA ADPCM, 8/16 bit PCM)
|
||||
- .xwb (PCM, Xbox IMA ADPCM, MS ADPCM, XMA, XWMA, ATRAC3)
|
||||
- .xwb+xwh (PCM, PSX ADPCM, ATRAC3)
|
||||
- .wav/lwav (unsigned 8 bit PCM, 16 bit PCM, GC DSP ADPCM, MS IMA ADPCM, XBOX IMA ADPCM)
|
||||
- .wem [lwav/logg/xma] (PCM, Wwise Vorbis, Wwise IMA ADPCM, XMA, XWMA, GC DSP ADPCM, Wwise Opus)
|
||||
- etc:
|
||||
- .2dx9 (MS ADPCM)
|
||||
- .aax (CRI ADX ADPCM)
|
||||
- .acm (InterPlay ACM)
|
||||
- .adp (GC DTK ADPCM)
|
||||
- .adx (CRI ADX ADPCM)
|
||||
- .afc (GC AFC ADPCM)
|
||||
- .ahx (MPEG-2 Layer II)
|
||||
- .aix (CRI ADX ADPCM)
|
||||
- .at3 (Sony ATRAC3 / ATRAC3plus)
|
||||
- .aud (Silicon Knights Vorbis)
|
||||
- .baf (PSX configurable ADPCM)
|
||||
- .bgw (PSX configurable ADPCM)
|
||||
- .bnsf (G.722.1)
|
||||
- .caf (Apple IMA4 ADPCM, others)
|
||||
- .dec/de2 (MS ADPCM)
|
||||
- .hca (CRI High Compression Audio)
|
||||
- .pcm/kcey (DVI IMA ADPCM)
|
||||
- .lsf (LSF ADPCM)
|
||||
- .mc3 (Paradigm MC3 ADPCM)
|
||||
- .mp4/lmp4 (AAC)
|
||||
- .msf (PCM, PSX ADPCM, ATRAC3, MP3)
|
||||
- .mtaf (Konami ADPCM)
|
||||
- .mta2 (Konami XAS-like ADPCM)
|
||||
- .mwv (Level-5 0x555 ADPCM)
|
||||
- .ogg/logg (Ogg Vorbis)
|
||||
- .ogl (Shin'en Vorbis)
|
||||
- .rsf (CCITT G.721 ADPCM)
|
||||
- .sab (Worms 4 soundpacks)
|
||||
- .s14/sss (G.722.1)
|
||||
- .sc (Activision EXAKT SASSC DPCM)
|
||||
- .scd (MS ADPCM, MPEG Audio, 16 bit PCM)
|
||||
- .sd9 (MS ADPCM)
|
||||
- .smp (MS ADPCM)
|
||||
- .spw (PSX configurable ADPCM)
|
||||
- .stm/lstm [amts/ps2stm/stma] (16 bit PCM, DVI IMA ADPCM, GC DSP ADPCM)
|
||||
- .str (SDX2 DPCM)
|
||||
- .stx (GC AFC ADPCM)
|
||||
- .ulw (u-Law PCM)
|
||||
- .um3 (Ogg Vorbis)
|
||||
- .xa (CD-ROM XA audio)
|
||||
- .xma (MS XMA/XMA2)
|
||||
- .sb0/sb1/sb2/sb3/sb4/sb5/sb6/sb7 (many)
|
||||
- .sm0/sm1/sm2/sm3/sm4/sm5/sm6/sm7 (many)
|
||||
- .bao/pk (many)
|
||||
- artificial/generic headers:
|
||||
- .genh (lots)
|
||||
- .txth (lots)
|
||||
- loop assists:
|
||||
- .mus (playlist for .acm)
|
||||
- .pos (loop info for .wav)
|
||||
- .sli (loop info for .ogg)
|
||||
- .sfl (loop info for .ogg)
|
||||
- other:
|
||||
- .adxkey (decryption key for .adx)
|
||||
- .ahxkey (decryption key for .ahx)
|
||||
- .hcakey (decryption key for .hca)
|
||||
- .fsbkey (decryption key for .fsb)
|
||||
- .bnsfkey (decryption key for .bnsf)
|
||||
- .txtp (per song segment/layer handler and player configuration)
|
||||
|
||||
|
||||
## Supported codec types
|
||||
Quick list of most 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 32-bit float
|
||||
- u-Law/a-LAW
|
||||
- CRI ADX (standard, fixed, exponential, encrypted)
|
||||
- Nintendo DSP ADPCM a.k.a GC ADPCM
|
||||
- Nintendo DTK ADPCM
|
||||
- Nintendo AFC ADPCM
|
||||
- ITU-T G.721
|
||||
- CD-ROM XA ADPCM
|
||||
- Sony PSX ADPCM a.k.a VAG (standard, badflags, configurable, extended)
|
||||
- Sony HEVAG
|
||||
- Electronic Arts EA-XA (stereo, mono, Maxis)
|
||||
- Electronic Arts EA-XAS (v0, v1)
|
||||
- DVI/IMA ADPCM (stereo/mono + high/low nibble, 3DS, Quantic Dream, SNDS, etc)
|
||||
- Microsoft MS IMA ADPCM (standard, Xbox, NDS, Radical, Wwise, FSB, WV6, etc)
|
||||
- Microsoft MS ADPCM (standard, Cricket Audio)
|
||||
- Westwood VBR ADPCM
|
||||
- Yamaha ADPCM (AICA, Aska)
|
||||
- Procyon Studio ADPCM
|
||||
- Level-5 0x555 ADPCM
|
||||
- lsf ADPCM
|
||||
- Konami MTAF ADPCM
|
||||
- Konami MTA2 ADPCM
|
||||
- Paradigm MC3 ADPCM
|
||||
- FMOD FADPCM 4-bit ADPCM
|
||||
- Konami XMD 4-bit ADPCM
|
||||
- Platinum 4-bit ADPCM
|
||||
- Argonaut ASF 4-bit ADPCM
|
||||
- Tantalus 4-bit ADPCM
|
||||
- Ocean DSA 4-bit ADPCM
|
||||
- Circus XPCM ADPCM
|
||||
- Circus XPCM VQ
|
||||
- OKI 4-bit ADPCM (16-bit output, 4-shift, PC-FX)
|
||||
- Ubisoft 4/6-bit ADPCM
|
||||
- Tiger Game.com ADPCM
|
||||
- LucasArts iMUSE VBR ADPCM
|
||||
- CompressWave (CWav) Huffman ADPCM
|
||||
- SDX2 2:1 Squareroot-Delta-Exact compression DPCM
|
||||
- CBD2 2:1 Cuberoot-Delta-Exact compression DPCM
|
||||
- Activision EXAKT SASSC DPCM
|
||||
- Xilam DERF DPCM
|
||||
- InterPlay ACM
|
||||
- VisualArt's NWA
|
||||
- Electronic Arts MicroTalk a.k.a. UTK or UMT
|
||||
- Relic Codec
|
||||
- CRI HCA
|
||||
- tri-Ace PS2 Codec
|
||||
- Xiph Vorbis (Ogg, FSB5, Wwise, OGL, Silicon Knights)
|
||||
- MPEG MP1/2/3 (standard, AHX, XVAG, FSB, AWC, P3D, EA, etc)
|
||||
- ITU-T G.722.1 annex C a.k.a. Polycom Siren 14 (Namco)
|
||||
- ITU-T G.719 annex B a.k.a. Polycom Siren 22
|
||||
- Electronic Arts EASpeex
|
||||
- Electronic Arts EALayer3
|
||||
- Electronic Arts EA-XMA
|
||||
- Sony ATRAC3, ATRAC3plus
|
||||
- Sony ATRAC9
|
||||
- Microsoft XMA1/2
|
||||
- Microsoft WMA v1, WMA v2, WMAPro
|
||||
- AAC
|
||||
- Bink
|
||||
- AC3/SPDIF
|
||||
- Xiph Opus (Ogg, Switch, EA, UE4, Exient)
|
||||
- Xiph CELT (FSB)
|
||||
- Musepack
|
||||
- FLAC
|
||||
- Others
|
||||
|
||||
Sometimes standard codecs come in non-standard layouts that aren't normally
|
||||
supported by other players (like multiple `.ogg` or `.mp3` files chunked and
|
||||
interleaved together in custom ways).
|
||||
|
||||
Some codecs are not fully correct compared to the games due to minor bugs, but
|
||||
in most cases it isn't audible, and general accuracy is high, with emphasis in
|
||||
proper support of encoder delay, accurate sample counts and seeking that other
|
||||
plugins may lack.
|
||||
|
||||
Note that vgmstream doesn't (can't) reproduce in-game music 1:1, as internal
|
||||
resampling, filters, volume, etc, are not replicated.
|
||||
398
doc/USAGE.md
398
doc/USAGE.md
@ -38,8 +38,8 @@ automatically, though not all may enabled at the moment due to build scripts iss
|
||||
*Windows*: unzip `test.exe` and follow the above instructions for installing needed extra files.
|
||||
`test.exe` is used for historical reasons, but you can call it `vgmstream-cli.exe`, anyway.
|
||||
|
||||
*Others*: build instructions can be found in doc/BUILD.md document in vgmstream's source
|
||||
code (can be compiled with CMake/Make/autotools).
|
||||
*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:
|
||||
- `test.exe -o happy.wav happy.adx` to decode `happy.adx` to `happy.wav`.
|
||||
@ -64,17 +64,7 @@ Output filename in `-o` may use wildcards:
|
||||
- `?f`: input filename
|
||||
|
||||
For example `test.exe -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`).
|
||||
|
||||
For files containing multiple subsongs, you can write them all using some flags.
|
||||
**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).
|
||||
- `test.exe -s 1 -S 100 file.bank`: writes from subsong 1 to subsong 100
|
||||
- `test.exe -s 101 -S 0 file.bank`: writes from subsong 101 to max subsong (automatically changes 0 to max)
|
||||
- `test.exe -S 0 file.bank`: writes from subsong 1 to max subsong
|
||||
- `test.exe -s 1 -S 5 -o bgm.wav file.bank`: writes 5 subsongs, but all overwrite the same file = wrong.
|
||||
- `test.exe -s 1 -S 5 -o bgm_?02s.wav file.bank`: writes 5 subsongs, each named differently = correct.
|
||||
Default output filename is `?f.wav`, or `?f#?s.wav` if you set subsongs (`-s/-S`).
|
||||
|
||||
|
||||
### in_vgmstream (Winamp plugin)
|
||||
@ -89,6 +79,17 @@ vgmstream as *"NOT LOADED"* that means extra DLL files aren't in the correct
|
||||
place.
|
||||
|
||||
|
||||
### 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*
|
||||
|
||||
A known quirk is that when loop options or tags change, playlist info won't refresh
|
||||
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.
|
||||
@ -106,28 +107,16 @@ XMPlay cannot support subsongs due to player limitations (with any plugin), try
|
||||
using *TXTP* instead (explained below).
|
||||
|
||||
|
||||
### 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*
|
||||
|
||||
A known quirk is that when loop options or tags change, playlist info won't refresh
|
||||
automatically. You need to manually refresh it by selecting songs and doing
|
||||
**shift + right click > Tagging > Reload info from file(s)**.
|
||||
|
||||
|
||||
### Audacious plugin
|
||||
*Windows*: not possible at the moment.
|
||||
|
||||
*Others*: needs to be manually built. Instructions can be found in doc/BUILD.md
|
||||
*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).
|
||||
|
||||
|
||||
### vgmstream123 (command line player)
|
||||
*Windows/Linux*: needs to be manually built. Instructions can be found in the
|
||||
*doc/BUILD.md* document in vgmstream's source code. On Windows it needs `libao.dll`
|
||||
and appropriate includes.
|
||||
*[BUILD.md](BUILD.md)* document. On Windows it needs `libao.dll` and appropriate includes.
|
||||
|
||||
Usage: `vgmstream123 [options] INFILE ...`
|
||||
|
||||
@ -159,9 +148,24 @@ handling.
|
||||
|
||||
### Subsongs
|
||||
Certain container formats have multiple audio files, usually called "subsongs", often
|
||||
not meant to be extracted (no simple separation). Some plugins are able to "unpack"
|
||||
those files automatically into the playlist. For others without support, you can create
|
||||
multiple .txtp (explained below) to select one of the subsongs (like `bgm.sxd#10.txtp`).
|
||||
not meant to be extracted (no simple separation).
|
||||
|
||||
With CLI tools, you can select a subsong using the `-s` flag followed by a number, for example:
|
||||
`text.exe -s 5 file.bank`.
|
||||
|
||||
For files containing multiple subsongs, you can write them all using some flags.
|
||||
**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).
|
||||
- `test.exe -s 1 -S 100 file.bank`: writes from subsong 1 to subsong 100
|
||||
- `test.exe -s 101 -S 0 file.bank`: writes from subsong 101 to max subsong (automatically changes 0 to max)
|
||||
- `test.exe -S 0 file.bank`: writes from subsong 1 to max subsong
|
||||
- `test.exe -s 1 -S 5 -o bgm.wav file.bank`: writes 5 subsongs, but all overwrite the same file = wrong.
|
||||
- `test.exe -s 1 -S 5 -o bgm_?02s.wav file.bank`: writes 5 subsongs, each named differently = correct.
|
||||
|
||||
Some plugins are able to "unpack" those files automatically into the playlist. For others without
|
||||
support, you can create multiple .txtp (explained below) to select one of the subsongs (like
|
||||
`bgm.sxd#10.txtp`).
|
||||
|
||||
You can use this python script to autogenerate one `.txtp` per subsong:
|
||||
https://github.com/vgmstream/vgmstream/tree/master/cli/tools/txtp_maker.py
|
||||
@ -727,337 +731,3 @@ 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).
|
||||
|
||||
|
||||
## Supported codec types
|
||||
Quick list of most 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 32-bit float
|
||||
- u-Law/a-LAW
|
||||
- CRI ADX (standard, fixed, exponential, encrypted)
|
||||
- Nintendo DSP ADPCM a.k.a GC ADPCM
|
||||
- Nintendo DTK ADPCM
|
||||
- Nintendo AFC ADPCM
|
||||
- ITU-T G.721
|
||||
- CD-ROM XA ADPCM
|
||||
- Sony PSX ADPCM a.k.a VAG (standard, badflags, configurable, extended)
|
||||
- Sony HEVAG
|
||||
- Electronic Arts EA-XA (stereo, mono, Maxis)
|
||||
- Electronic Arts EA-XAS (v0, v1)
|
||||
- DVI/IMA ADPCM (stereo/mono + high/low nibble, 3DS, Quantic Dream, SNDS, etc)
|
||||
- Microsoft MS IMA ADPCM (standard, Xbox, NDS, Radical, Wwise, FSB, WV6, etc)
|
||||
- Microsoft MS ADPCM (standard, Cricket Audio)
|
||||
- Westwood VBR ADPCM
|
||||
- Yamaha ADPCM (AICA, Aska)
|
||||
- Procyon Studio ADPCM
|
||||
- Level-5 0x555 ADPCM
|
||||
- lsf ADPCM
|
||||
- Konami MTAF ADPCM
|
||||
- Konami MTA2 ADPCM
|
||||
- Paradigm MC3 ADPCM
|
||||
- FMOD FADPCM 4-bit ADPCM
|
||||
- Konami XMD 4-bit ADPCM
|
||||
- Platinum 4-bit ADPCM
|
||||
- Argonaut ASF 4-bit ADPCM
|
||||
- Tantalus 4-bit ADPCM
|
||||
- Ocean DSA 4-bit ADPCM
|
||||
- Circus XPCM ADPCM
|
||||
- Circus XPCM VQ
|
||||
- OKI 4-bit ADPCM (16-bit output, 4-shift, PC-FX)
|
||||
- Ubisoft 4/6-bit ADPCM
|
||||
- Tiger Game.com ADPCM
|
||||
- LucasArts iMUSE VBR ADPCM
|
||||
- CompressWave (CWav) Huffman ADPCM
|
||||
- SDX2 2:1 Squareroot-Delta-Exact compression DPCM
|
||||
- CBD2 2:1 Cuberoot-Delta-Exact compression DPCM
|
||||
- Activision EXAKT SASSC DPCM
|
||||
- Xilam DERF DPCM
|
||||
- InterPlay ACM
|
||||
- VisualArt's NWA
|
||||
- Electronic Arts MicroTalk a.k.a. UTK or UMT
|
||||
- Relic Codec
|
||||
- CRI HCA
|
||||
- tri-Ace PS2 Codec
|
||||
- Xiph Vorbis (Ogg, FSB5, Wwise, OGL, Silicon Knights)
|
||||
- MPEG MP1/2/3 (standard, AHX, XVAG, FSB, AWC, P3D, EA, etc)
|
||||
- ITU-T G.722.1 annex C a.k.a. Polycom Siren 14 (Namco)
|
||||
- ITU-T G.719 annex B a.k.a. Polycom Siren 22
|
||||
- Electronic Arts EASpeex
|
||||
- Electronic Arts EALayer3
|
||||
- Electronic Arts EA-XMA
|
||||
- Sony ATRAC3, ATRAC3plus
|
||||
- Sony ATRAC9
|
||||
- Microsoft XMA1/2
|
||||
- Microsoft WMA v1, WMA v2, WMAPro
|
||||
- AAC
|
||||
- Bink
|
||||
- AC3/SPDIF
|
||||
- Xiph Opus (Ogg, Switch, EA, UE4, Exient)
|
||||
- Xiph CELT (FSB)
|
||||
- Musepack
|
||||
- FLAC
|
||||
- Others
|
||||
|
||||
Sometimes standard codecs come in non-standard layouts that aren't normally
|
||||
supported by other players (like multiple `.ogg` or `.mp3` files chunked and
|
||||
interleaved together in custom ways).
|
||||
|
||||
Some codecs are not fully correct compared to the games due to minor bugs, but
|
||||
in most cases it isn't audible, and general accuracy is high, with emphasis in
|
||||
proper support of encoder delay, accurate sample counts and seeking that other
|
||||
plugins may lack.
|
||||
|
||||
Note that vgmstream doesn't (can't) reproduce in-game music 1:1, as internal
|
||||
resampling, filters, volume, etc, are not replicated.
|
||||
|
||||
|
||||
## Supported file types
|
||||
As manakoAT likes to say, the extension doesn't really mean anything, but it's
|
||||
the most obvious way to identify files.
|
||||
|
||||
This list is not complete and many other files are supported.
|
||||
|
||||
- PS2/PSX ADPCM:
|
||||
- .ads/.ss2
|
||||
- .ass
|
||||
- .ast
|
||||
- .bg00
|
||||
- .bmdx
|
||||
- .ccc
|
||||
- .cnk
|
||||
- .dxh
|
||||
- .enth
|
||||
- .fag
|
||||
- .filp
|
||||
- .gcm
|
||||
- .gms
|
||||
- .hgc1
|
||||
- .ikm
|
||||
- .ild
|
||||
- .ivb
|
||||
- .joe
|
||||
- .kces
|
||||
- .khv
|
||||
- .leg
|
||||
- .mcg
|
||||
- .mib, .mi4 (w/ or w/o .mih)
|
||||
- .mic
|
||||
- .mihb (merged mih+mib)
|
||||
- .msa
|
||||
- .msvp
|
||||
- .musc
|
||||
- .npsf
|
||||
- .pnb
|
||||
- .psh
|
||||
- .rkv
|
||||
- .rnd
|
||||
- .rstm
|
||||
- .rws
|
||||
- .rxw
|
||||
- .snd
|
||||
- .sfs
|
||||
- .sl3
|
||||
- .smpl (w/ bad flags)
|
||||
- .ster
|
||||
- .str+.sth
|
||||
- .str (MGAV blocked)
|
||||
- .sts
|
||||
- .svag
|
||||
- .svs
|
||||
- .tec (w/ bad flags)
|
||||
- .tk5 (w/ bad flags)
|
||||
- .vas
|
||||
- .vag
|
||||
- .vgs (w/ bad flags)
|
||||
- .vig
|
||||
- .vpk
|
||||
- .vs
|
||||
- .vsf
|
||||
- .wp2
|
||||
- .xa2
|
||||
- .xa30
|
||||
- .xwb+xwh
|
||||
- GC/Wii/3DS DSP ADPCM:
|
||||
- .aaap
|
||||
- .agsc
|
||||
- .asr
|
||||
- .bns
|
||||
- .bo2
|
||||
- .capdsp
|
||||
- .cfn
|
||||
- .ddsp
|
||||
- .dsp
|
||||
- standard, optional dual file stereo
|
||||
- RS03
|
||||
- Cstr
|
||||
- _lr.dsp
|
||||
- MPDS
|
||||
- .gca
|
||||
- .gcm
|
||||
- .gsp+.gsp
|
||||
- .hps
|
||||
- .idsp
|
||||
- .ish+.isd
|
||||
- .lps
|
||||
- .mca
|
||||
- .mpdsp
|
||||
- .mss
|
||||
- .mus (not quite right)
|
||||
- .ndp
|
||||
- .pdt
|
||||
- .sdt
|
||||
- .smp
|
||||
- .sns
|
||||
- .spt+.spd
|
||||
- .ssm
|
||||
- .stm/.dsp
|
||||
- .str
|
||||
- .str+.sth
|
||||
- .sts
|
||||
- .swd
|
||||
- .thp, .dsp
|
||||
- .tydsp
|
||||
- .vjdsp
|
||||
- .waa, .wac, .wad, .wam
|
||||
- .was
|
||||
- .wsd
|
||||
- .wsi
|
||||
- .ydsp
|
||||
- .ymf
|
||||
- .zwdsp
|
||||
- PCM:
|
||||
- .aiff (8 bit, 16 bit)
|
||||
- .asd (16 bit)
|
||||
- .baka (16 bit)
|
||||
- .bh2pcm (16 bit)
|
||||
- .dmsg (16 bit)
|
||||
- .gcsw (16 bit)
|
||||
- .gcw (16 bit)
|
||||
- .his (8 bit)
|
||||
- .int (16 bit)
|
||||
- .pcm (8 bit, 16 bit)
|
||||
- .kraw (16 bit)
|
||||
- .raw (16 bit)
|
||||
- .rwx (16 bit)
|
||||
- .sap (16 bit)
|
||||
- .snd (16 bit)
|
||||
- .sps (16 bit)
|
||||
- .str (16 bit)
|
||||
- .xss (16 bit)
|
||||
- .voi (16 bit)
|
||||
- .wb (16 bit)
|
||||
- .zsd (8 bit)
|
||||
- Xbox IMA ADPCM:
|
||||
- .matx
|
||||
- .wavm
|
||||
- .wvs
|
||||
- .xmu
|
||||
- .xvas
|
||||
- .xwav
|
||||
- Yamaha AICA ADPCM:
|
||||
- .adpcm
|
||||
- .dcs+.dcsw
|
||||
- .str
|
||||
- .spsd
|
||||
- IMA ADPCM:
|
||||
- .bar (IMA ADPCM)
|
||||
- .pcm/dvi (DVI IMA ADPCM)
|
||||
- .hwas (IMA ADPCM)
|
||||
- .dvi/idvi (DVI IMA ADPCM)
|
||||
- .ivaud (IMA ADPCM)
|
||||
- .myspd (IMA ADPCM)
|
||||
- .strm (IMA ADPCM)
|
||||
- multi:
|
||||
- .aifc (SDX2 DPCM, DVI IMA ADPCM)
|
||||
- .asf/as4 (8/16 bit PCM, DVI IMA ADPCM)
|
||||
- .ast (GC AFC ADPCM, 16 bit PCM)
|
||||
- .aud (IMA ADPCM, WS DPCM)
|
||||
- .aus (PSX ADPCM, Xbox IMA ADPCM)
|
||||
- .brstm (GC DSP ADPCM, 8/16 bit PCM)
|
||||
- .emff (PSX APDCM, GC DSP ADPCM)
|
||||
- .fsb/wii (PSX ADPCM, GC DSP ADPCM, Xbox IMA ADPCM, MPEG audio, FSB Vorbis, MS XMA)
|
||||
- .msf (PCM, PSX ADPCM, ATRAC3, MP3)
|
||||
- .musx (PSX ADPCM, Xbox IMA ADPCM, DAT4 IMA ADPCM)
|
||||
- .nwa (16 bit PCM, NWA DPCM)
|
||||
- .p3d (Radical ADPCM, Radical MP3, XMA2)
|
||||
- .psw (PSX ADPCM, GC DSP ADPCM)
|
||||
- .rwar, .rwav (GC DSP ADPCM, 8/16 bit PCM)
|
||||
- .rws (PSX ADPCM, XBOX IMA ADPCM, GC DSP ADPCM, 16 bit PCM)
|
||||
- .rwsd (GC DSP ADPCM, 8/16 bit PCM)
|
||||
- .rsd (PSX ADPCM, 16 bit PCM, GC DSP ADPCM, Xbox IMA ADPCM, Radical ADPCM)
|
||||
- .rrds (NDS IMA ADPCM)
|
||||
- .sad (GC DSP ADPCM, NDS IMA ADPCM, Procyon Studios NDS ADPCM)
|
||||
- .sgd/sgb+sgh/sgx (PSX ADPCM, ATRAC3plus, AC3)
|
||||
- .seg (Xbox IMA ADPCM, PS2 ADPCM)
|
||||
- .sng/asf/str/eam/aud (8/16 bit PCM, EA-XA ADPCM, PSX ADPCM, GC DSP ADPCM, XBOX IMA ADPCM, MPEG audio, EALayer3)
|
||||
- .strm (NDS IMA ADPCM, 8/16 bit PCM)
|
||||
- .sb0..7 (Ubi IMA ADPCM, GC DSP ADPCM, PSX ADPCM, Xbox IMA ADPCM, ATRAC3)
|
||||
- .swav (NDS IMA ADPCM, 8/16 bit PCM)
|
||||
- .xwb (PCM, Xbox IMA ADPCM, MS ADPCM, XMA, XWMA, ATRAC3)
|
||||
- .xwb+xwh (PCM, PSX ADPCM, ATRAC3)
|
||||
- .wav/lwav (unsigned 8 bit PCM, 16 bit PCM, GC DSP ADPCM, MS IMA ADPCM, XBOX IMA ADPCM)
|
||||
- .wem [lwav/logg/xma] (PCM, Wwise Vorbis, Wwise IMA ADPCM, XMA, XWMA, GC DSP ADPCM, Wwise Opus)
|
||||
- etc:
|
||||
- .2dx9 (MS ADPCM)
|
||||
- .aax (CRI ADX ADPCM)
|
||||
- .acm (InterPlay ACM)
|
||||
- .adp (GC DTK ADPCM)
|
||||
- .adx (CRI ADX ADPCM)
|
||||
- .afc (GC AFC ADPCM)
|
||||
- .ahx (MPEG-2 Layer II)
|
||||
- .aix (CRI ADX ADPCM)
|
||||
- .at3 (Sony ATRAC3 / ATRAC3plus)
|
||||
- .aud (Silicon Knights Vorbis)
|
||||
- .baf (PSX configurable ADPCM)
|
||||
- .bgw (PSX configurable ADPCM)
|
||||
- .bnsf (G.722.1)
|
||||
- .caf (Apple IMA4 ADPCM, others)
|
||||
- .dec/de2 (MS ADPCM)
|
||||
- .hca (CRI High Compression Audio)
|
||||
- .pcm/kcey (DVI IMA ADPCM)
|
||||
- .lsf (LSF ADPCM)
|
||||
- .mc3 (Paradigm MC3 ADPCM)
|
||||
- .mp4/lmp4 (AAC)
|
||||
- .msf (PCM, PSX ADPCM, ATRAC3, MP3)
|
||||
- .mtaf (Konami ADPCM)
|
||||
- .mta2 (Konami XAS-like ADPCM)
|
||||
- .mwv (Level-5 0x555 ADPCM)
|
||||
- .ogg/logg (Ogg Vorbis)
|
||||
- .ogl (Shin'en Vorbis)
|
||||
- .rsf (CCITT G.721 ADPCM)
|
||||
- .sab (Worms 4 soundpacks)
|
||||
- .s14/sss (G.722.1)
|
||||
- .sc (Activision EXAKT SASSC DPCM)
|
||||
- .scd (MS ADPCM, MPEG Audio, 16 bit PCM)
|
||||
- .sd9 (MS ADPCM)
|
||||
- .smp (MS ADPCM)
|
||||
- .spw (PSX configurable ADPCM)
|
||||
- .stm/lstm [amts/ps2stm/stma] (16 bit PCM, DVI IMA ADPCM, GC DSP ADPCM)
|
||||
- .str (SDX2 DPCM)
|
||||
- .stx (GC AFC ADPCM)
|
||||
- .ulw (u-Law PCM)
|
||||
- .um3 (Ogg Vorbis)
|
||||
- .xa (CD-ROM XA audio)
|
||||
- .xma (MS XMA/XMA2)
|
||||
- .sb0/sb1/sb2/sb3/sb4/sb5/sb6/sb7 (many)
|
||||
- .sm0/sm1/sm2/sm3/sm4/sm5/sm6/sm7 (many)
|
||||
- .bao/pk (many)
|
||||
- artificial/generic headers:
|
||||
- .genh (lots)
|
||||
- .txth (lots)
|
||||
- loop assists:
|
||||
- .mus (playlist for .acm)
|
||||
- .pos (loop info for .wav)
|
||||
- .sli (loop info for .ogg)
|
||||
- .sfl (loop info for .ogg)
|
||||
- other:
|
||||
- .adxkey (decryption key for .adx)
|
||||
- .ahxkey (decryption key for .ahx)
|
||||
- .hcakey (decryption key for .hca)
|
||||
- .fsbkey (decryption key for .fsb)
|
||||
- .bnsfkey (decryption key for .bnsf)
|
||||
- .txtp (per song segment/layer handler and player configuration)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user