taglib/INSTALL.md

TagLib Installation

TagLib uses the CMake build system. As a user, you will most likely want to build TagLib in release mode and install it into a system-wide location. This can be done using the following commands:

cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release .
make
sudo make install

In order to build the included examples, use the BUILD_EXAMPLES option:

cmake -DBUILD_EXAMPLES=ON [...]

If you want to build TagLib without ZLib, you can use

cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release -DWITH_ZLIB=OFF .
make
sudo make install

See cmake(1) for generic help on running CMake.

Build Options

These are the most important build options. For details, have a look into the CMakeLists.txt file.

Option	Description
BUILD_SHARED_LIBS	Build shared libraries
CMAKE_BUILD_TYPE	Debug, Release, RelWithDebInfo, MinSizeRel
BUILD_EXAMPLES	Build examples
BUILD_BINDINGS	Build C bindings
BUILD_TESTING	Build unit tests
TRACE_IN_RELEASE	Enable debug output in release builds
WITH_ZLIB	Whether to build with ZLib (default ON)
ZLIB_ROOT	Where to find ZLib's root directory
ZLIB_INCLUDE_DIR	Where to find ZLib's include directory
ZLIB_LIBRARY	Where to find ZLib's library
CMAKE_INSTALL_PREFIX	Where to install Taglib
TAGLIB_INSTALL_SUFFIX	Suffix added to installed libraries, includes, ...
ENABLE_STATIC_RUNTIME	Link with MSVC runtime statically
BUILD_FRAMEWORK	Build a macOS framework
TESTS_DIR	Where to find unit test data (with data appended)
TESTS_TMPDIR	Where to create temporary files in unit tests

If you want to install TagLib 2 alongside TagLib 1, you can use -DTAGLIB_INSTALL_SUFFIX=-2 and make sure that BUILD_EXAMPLES is not ON for both versions. The installed files will then include bin/taglib-2-config, include/taglib-2, cmake/taglib-2, pkgconfig/taglib-2.pc, pkgconfig/taglib_c-2.pc and the libraries have a suffix "-2".

Compile Time Configuration of Supported Formats

To reduce the size of the library, it is possible to switch off supported file formats. By default, all formats are enabled. Support for MPEG files (MP3, AAC) and ID3 tags cannot be disabled. The following CMake options are available:

Option	Description
WITH_APE	Build with APE, MPC, WavPack (default ON)
WITH_ASF	Build with ASF (default ON)
WITH_DSF	Build with DSF (default ON)
WITH_MOD	Build with Tracker modules (default ON)
WITH_MP4	Build with MP4 (default ON)
WITH_RIFF	Build with AIFF, RIFF, WAV (default ON)
WITH_SHORTEN	Build with Shorten (default ON)
WITH_TRUEAUDIO	Build with TrueAudio (default ON)
WITH_VORBIS	Build with Vorbis, FLAC, Ogg, Opus (default ON)

Note that disabling formats will remove exported symbols from the library and thus break binary compatibility. These options should therefore only be used if the library is built specifically for a certain project. The public header files still contain the full API, if you use TagLib with a reduced set of formats, you can include taglib_config.h and use its definitions (prefixed with TAGLIB_, e.g. TAGLIB_WITH_APE), as it is done in examples/framelist.cpp.

Dependencies

A required dependency is utf8cpp. You can install the corresponding package (libutfcpp-dev on Ubuntu, utf8cpp in Homebrew, utfcpp in vcpkg) or fetch the Git submodule with git submodule update --init.

Optional dependencies are

• zlib: You can disable it with -DWITH_ZLIB=OFF, build and install it from the sources or use a package (zlib1g-dev on Ubuntu, zlib in vcpkg). It is needed for compressed ID3v2 frames.
• CppUnit: Is required for unit tests, which are disabled by default. If you enable them with -DBUILD_TESTING=ON, you can build and install it from the sources or use a package (libcppunit-dev on Ubuntu, cppunit in Homebrew, cppunit in vcpkg). If the unit tests are enabled, you can run them with your build tool (make check, ninja check) or via CMake cmake --build /path/to/build-dir --target check.

UNIX (Including Linux, BSD and macOS)

Building TagLib

On Linux, you can install the dependencies using the package manager of your distribution. On macOS with Homebrew, you can use brew install cppunit utf8cpp to install the dependencies.

# Adapt these environment variables to your directories
TAGLIB_SRC_DIR=$HOME/projects/taglib/src/taglib
TAGLIB_DST_DIR=$HOME/projects/taglib/src/build
cd $TAGLIB_SRC_DIR
cmake -B $TAGLIB_DST_DIR -DBUILD_SHARED_LIBS=ON -DVISIBILITY_HIDDEN=ON \
  -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON -DBUILD_BINDINGS=ON \
  -DCMAKE_BUILD_TYPE=Release
cmake --build $TAGLIB_DST_DIR --config Release
cmake --build $TAGLIB_DST_DIR --config Release --target check

# Install to ~/pkg folder
cmake --install $TAGLIB_DST_DIR --config Release --prefix $HOME/pkg --strip

# Run example from installed package
LD_LIBRARY_PATH=$HOME/pkg/lib $HOME/pkg/bin/tagreader /path/to/audio-file

Building a Project Using TagLib

As an example for an external application using TagLib, we create a folder taglib-client and copy the file tagreader.cpp from the examples folder of the TagLib sources into it. We then add this simple CMakeLists.txt.

cmake_minimum_required(VERSION 3.5.0)
project(taglib-client)
set(CMAKE_CXX_STANDARD 17)
find_package(ZLIB)
find_package(TagLib 2.0.0 REQUIRED)
add_executable(tagreader tagreader.cpp)
target_link_libraries(tagreader TagLib::tag)

To build into a folder build inside this directory, just run

# Set this to the path where TagLib is installed
TAGLIB_PREFIX=$HOME/pkg
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$TAGLIB_PREFIX
cmake --build build --config Release

build/tagreader /path/to/audio-file

If TagLib is installed in a standard location (e.g. /usr, /usr/local), its CMake configuration is found without setting CMAKE_INSTALL_PREFIX (or alternatives like CMAKE_PREFIX_PATH, CMAKE_SYSTEM_PREFIX_PATH).

To use the C-bindings with tagreader_c.c, you can change the last two lines in CMakeLists.txt to

add_executable(tagreader_c tagreader_c.c)
target_link_libraries(tagreader_c TagLib::tag_c)

Building a Project Using pkg-config

Before version 2.0, TagLib did not export CMake configuration, therefore pkg-config could be used. This is still possible.

Note, however, that pkg-config makes it more difficult to use packages which are not installed in a standard location. You can point pkg-config to search in non-standard locations for .pc-files, but they still contain the install locations defined when building TagLib. Since we did not give a CMAKE_INSTALL_PREFIX in the example above, the default /usr/local/ is used.

PKG_CONFIG_PATH=$HOME/pkg/lib/pkgconfig pkg-config --libs --cflags taglib
-I/usr/local/include -I/usr/local/include/taglib -L/usr/local/lib -ltag -lz

The following examples use the same build example with additional CMake parameters affecting the installation location.

• Using the default prefix -DCMAKE_INSTALL_PREFIX=/usr/local:

  -I/usr/local/include -I/usr/local/include/taglib -L/usr/local/lib -ltag -lz
  

• Using an absolute prefix -DCMAKE_INSTALL_PREFIX=/usr:

  -I/usr/include/taglib -ltag -lz
  

• Using absolute lib and include directories -DCMAKE_INSTALL_LIBDIR=/abs-lib -DCMAKE_INSTALL_INCLUDEDIR=/abs-include -DCMAKE_INSTALL_PREFIX=/usr:

  -I/abs-include -I/abs-include/taglib -L/abs-lib -ltag -lz
  

• Using relative lib and include directories -DCMAKE_INSTALL_LIBDIR=rel-lib -DCMAKE_INSTALL_INCLUDEDIR=rel-include -DCMAKE_INSTALL_PREFIX=/usr:

  -I/usr/rel-include -I/usr/rel-include/taglib -L/usr/rel-lib -ltag -lz
  

  This is the output of

  PKG_CONFIG_PATH=$HOME/pkg/rel-lib/pkgconfig pkg-config --libs --cflags taglib
  

  You could add --define-prefix to the pkg-config arguments to have the effective location $HOME/pkg/ instead of /usr/ in the output.

Therefore, the correct paths for our example package would be given when using the --define-prefix feature.

PKG_CONFIG_PATH=$HOME/pkg/lib/pkgconfig pkg-config --define-prefix --libs --cflags taglib

You can use pkg-config from CMake, however, relocation with --define-prefix is not supported.

cmake_minimum_required(VERSION 3.6.0)
project(taglib-client)
find_package(PkgConfig)
pkg_check_modules(TAGLIB REQUIRED IMPORTED_TARGET taglib)
add_executable(tagreader tagreader.cpp)
target_link_libraries(tagreader PkgConfig::TAGLIB)

Framework on macOS

On macOS, you might want to build a framework that can be easily integrated into your application. If you set the BUILD_FRAMEWORK option on, it will compile TagLib as a framework. For example, the following command can be used to build a framework with macOS 10.10 as the deployment target:

mkdir build; cd build
cmake .. -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTING=OFF \
  -DBUILD_FRAMEWORK=ON \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=10.10 \
  -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
make

For a 10.10 static library, use:

mkdir build; cd build
cmake .. -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTING=OFF \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=10.10 \
  -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
make

After make, and make install, add libtag. to your XCode project, and add the include folder to the project's User Header Search Paths.

Windows

Using Visual Studio Build Tools

For this example, we assume that you have the Visual Studio Build Tools 2022 installed. Additionally, you need cmake, which can be installed for example using scoop with scoop install cmake.

Building TagLib (MSVC)

You can build and install the dependencies utf8cpp and optionally zlib and CppUnit yourself, but it is probably easier using a package manager such as vcpkg, which can be installed using scoop install vcpkg and then install the dependencies using vcpkg install utfcpp zlib cppunit.

Now you can build TagLib from PowerShell.

# Adapt these environment variables to your directories
$env:TAGLIB_SRC_DIR = "${env:HOMEDRIVE}${env:HOMEPATH}/projects/taglib/src/taglib"
$env:TAGLIB_DST_DIR = "${env:HOMEDRIVE}${env:HOMEPATH}/projects/taglib/src/msvs_vcpkg_build"
cd $env:TAGLIB_SRC_DIR
cmake -B $env:TAGLIB_DST_DIR -DBUILD_SHARED_LIBS=ON -DVISIBILITY_HIDDEN=ON `
  -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON -DBUILD_BINDINGS=ON `
  -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" `
  -G "Visual Studio 17 2022"
cmake --build $env:TAGLIB_DST_DIR --config Release

# Add directories containing DLL dependencies to path
$env:Path += -join(";$env:TAGLIB_DST_DIR\taglib\Release;",
"$env:TAGLIB_DST_DIR\bindings\c\Release;",
"$env:VCPKG_ROOT\packages\cppunit_x64-windows\bin;",
"$env:VCPKG_ROOT\packages\utfcpp_x64-windows\bin;",
"$env:VCPKG_ROOT\packages\zlib_x64-windows\bin")
cmake --build $env:TAGLIB_DST_DIR --config Release --target check

# Install to \pkg folder on current drive
cmake --install $env:TAGLIB_DST_DIR --config Release --prefix /pkg --strip

# Static library
$env:TAGLIB_DST_DIR = "C:/Users/fle/projects/taglib/src/msvs_vcpkg_static_build"
cmake -B $env:TAGLIB_DST_DIR -DBUILD_SHARED_LIBS=OFF -DVISIBILITY_HIDDEN=ON `
  -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON -DBUILD_BINDINGS=ON `
  -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" `
  -G "Visual Studio 17 2022"
cmake --build $env:TAGLIB_DST_DIR --config Release

cmake --build $env:TAGLIB_DST_DIR --config Release --target check

# Install to \pkg_static folder on current drive
cmake --install $env:TAGLIB_DST_DIR --config Release --prefix /pkg_static --strip

Including ENABLE_STATIC_RUNTIME=ON indicates you want TagLib built using the static runtime library, rather than the DLL form of the runtime.

Building a Project Using TagLib (MSVC)

As an example for an external application using TagLib, we create a folder taglib-client and copy the file tagreader.cpp from the examples folder of the TagLib sources into it. We then add this simple CMakeLists.txt.

cmake_minimum_required(VERSION 3.5.0)
project(taglib-client)
set(CMAKE_CXX_STANDARD 17)
find_package(ZLIB)
find_package(TagLib 2.0.0 REQUIRED)
add_executable(tagreader tagreader.cpp)
target_link_libraries(tagreader TagLib::tag)

To build into a folder build inside this directory, just run

# Set this to the path where TagLib is installed
$env:TAGLIB_PREFIX = "/pkg"
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$env:TAGLIB_PREFIX" `
  -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" `
  -G "Visual Studio 17 2022"
cmake --build build --config Release

# Add directories containing DLL dependencies to path
$env:Path += ";$env:TAGLIB_PREFIX\bin;$env:VCPKG_ROOT\packages\zlib_x64-windows\bin"
build\Release\tagreader /path/to/audio-file

To use the C-bindings with tagreader_c.c, you can change the last two lines in CMakeLists.txt to

add_executable(tagreader_c tagreader_c.c)
target_link_libraries(tagreader_c TagLib::tag_c)

If you link against a static TagLib, you have to adapt the installation path (e.g. "/pkg_static") and add the following line to CMakeLists.txt

target_compile_definitions(tagreader_c PRIVATE TAGLIB_STATIC)

Using MSYS2

Building TagLib (MSYS2)

To build TagLib using Clang from MSYS, install msys2, then start the MSYS CLANG64 shell and install the dependencies as they are specified in the MSYS recipe for TagLib.

pacman -Suy
pacman -S mingw-w64-clang-x86_64-gcc-libs mingw-w64-clang-x86_64-zlib \
  mingw-w64-clang-x86_64-cc mingw-w64-clang-x86_64-cmake \
  mingw-w64-clang-x86_64-cppunit mingw-w64-clang-x86_64-ninja

Then you can build TagLib from the MSYS CLANG64 Bash.

# Adapt these environment variables to your directories
TAGLIB_SRC_DIR=$HOME/projects/taglib/src/taglib
TAGLIB_DST_DIR=$HOME/projects/taglib/src/msys_build
cd $TAGLIB_SRC_DIR
cmake -B $TAGLIB_DST_DIR -DBUILD_SHARED_LIBS=ON -DVISIBILITY_HIDDEN=ON \
  -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON -DBUILD_BINDINGS=ON \
  -DCMAKE_BUILD_TYPE=Release -G Ninja
cmake --build $TAGLIB_DST_DIR --config Release

PATH=$PATH:/clang64/bin:$TAGLIB_DST_DIR/taglib:$TAGLIB_DST_DIR/bindings/c \
  cmake --build $TAGLIB_DST_DIR --config Release --target check

# Install to /pkg_msys folder inside MSYS root (e.g. C:/msys64/pkg_msys/)
cmake --install $TAGLIB_DST_DIR --config Release --prefix /pkg_msys --strip

Building a Project Using TagLib (MSYS2)

As an example for an external application using TagLib, we create a folder taglib-client and copy the file tagreader.cpp from the examples folder of the TagLib sources into it. We then add this simple CMakeLists.txt.

cmake_minimum_required(VERSION 3.5.0)
project(taglib-client)
set(CMAKE_CXX_STANDARD 17)
find_package(ZLIB)
find_package(TagLib 2.0.0 REQUIRED)
add_executable(tagreader tagreader.cpp)
target_link_libraries(tagreader TagLib::tag)

To build into a folder build_msys inside this directory, just run

# Set this to the path where TagLib is installed
TAGLIB_PREFIX=/pkg_msys
cmake -B build_msys -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$TAGLIB_PREFIX -G Ninja
cmake --build build_msys --config Release

PATH=$PATH:$TAGLIB_PREFIX/bin
  build_msys/tagreader /path/to/audio-file

To use the C-bindings with tagreader_c.c, you can change the last two lines in CMakeLists.txt to

add_executable(tagreader_c tagreader_c.c)
target_link_libraries(tagreader_c TagLib::tag_c)

Using MinGW

The instructions for MSYS2 can also be used to build with MinGW. You could use Git Bash together with the MinGW provided by Qt.

# Adapt these environment variables to your directories
PATH=$PATH:/c/Qt/Tools/mingw1120_64/bin
TAGLIB_SRC_DIR=$HOME/projects/taglib/src/taglib
TAGLIB_DST_DIR=$HOME/projects/taglib/src/mingw_build
cd $TAGLIB_SRC_DIR
cmake -B $TAGLIB_DST_DIR -DBUILD_SHARED_LIBS=ON -DVISIBILITY_HIDDEN=ON \
  -DBUILD_EXAMPLES=ON -DBUILD_BINDINGS=ON -DWITH_ZLIB=OFF \
  -DCMAKE_BUILD_TYPE=Release -G 'MinGW Makefiles'
cmake --build $TAGLIB_DST_DIR --config Release

PATH=$PATH:$TAGLIB_DST_DIR/taglib \
  $TAGLIB_DST_DIR/examples/tagreader /path/to/audio-file

# Install to C:\pkg_mingw
cmake --install $TAGLIB_DST_DIR --config Release --prefix /c/pkg_mingw --strip

The installed package can then be used by other projects.

TAGLIB_PREFIX=/c/pkg_mingw
cmake -B build_mingw -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$TAGLIB_PREFIX -G 'MinGW Makefiles'
cmake --build build_mingw --config Release

PATH=$PATH:$TAGLIB_PREFIX/bin
  build_mingw/tagreader /path/to/audio-file

Android

Using vcpkg

The bash script below can be used to build TagLib for Android using vcpkg. It must be started in the parent folder of the taglib source folder and will build in a folder android_build and install into android_pkg. The package and the unit tests are then transferred to an Android device and the unit tests are run on the device.

Note that TESTS_TMPDIR is set because there is no system-wide temporary folder on Android. TESTS_DIR is set to run the tests on the target.

# You may have to adapt the NDK and vcpkg paths and the ABI/triplet.

export ANDROID_NDK_HOME=$HOME/Development/android-sdk/ndk/23.1.7779620
export VCPKG_ROOT=$HOME/Development/vcpkg
PATH=$PATH:$VCPKG_ROOT

# armeabi-v7a/arm-android or arm64-v8a/arm64-android or x86/x86-android or x86_64/x64-android
android_abi=armeabi-v7a
vcpkg_target_triplet=arm-android

vcpkg_toolchain_file=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
android_toolchain_file=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake

vcpkg install --triplet $vcpkg_target_triplet utfcpp zlib cppunit

cmake -B android_build -S taglib \
  -DCMAKE_TOOLCHAIN_FILE=$vcpkg_toolchain_file \
  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$android_toolchain_file \
  -DVCPKG_TARGET_TRIPLET=$vcpkg_target_triplet \
  -DANDROID_ABI=$android_abi \
  -GNinja -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release \
  -DVISIBILITY_HIDDEN=ON -DENABLE_CCACHE=ON -DBUILD_EXAMPLES=ON -DBUILD_TESTING=ON \
  -DTESTS_DIR=/data/local/tmp/tests/ -DTESTS_TMPDIR=/data/local/tmp
cmake --build android_build --config Release
cmake --install android_build --config Release --prefix android_pkg --strip
cp -a android_build/tests/test_runner android_pkg/bin/

if hash adb 2>/dev/null; then
  adb push android_pkg /data/local/tmp/
  adb push android_build/tests/test_runner /data/local/tmp/tests/test_runner
  adb push taglib/tests/data /data/local/tmp/tests/
  adb shell "env LD_LIBRARY_PATH=/data/local/tmp/android_pkg/lib /data/local/tmp/tests/test_runner"
  # You could also try an example binary:
  # adb shell "env LD_LIBRARY_PATH=/data/local/tmp/android_pkg/lib /data/local/tmp/android_pkg/bin/tagreader  '/sdcard/Music/Some Album/A Track.mp3'"
fi