Rocky Linux 安装 libltc、ltc-tools 和 ltcdump

一、问题背景

LTC（Linear Time Code，线性时间码）通常以音频波形的形式存在。要从 WAV 文件中读取其中的时间码，需要一个能够解析 LTC 波形的解码器。本文记录在 Rocky Linux（或CentOS）上安装 libltc、ltc-tools，并最终得到 ltcdump 的完整过程。

本文的目标不是安装一个名为 ltcdump 的系统软件包。实际情况是：ltcdump 是 ltc-tools 源码中的命令行程序，它依赖 libltc 完成 LTC 解码，并依赖 libsndfile 读取 WAV 音频文件。

适用场景：服务器需要分析已经录制好的 LTC WAV 文件，或者先用命令行工具确认 LTC 音频是否包含可解码的时间码。

二、三个组件是什么关系

组件	作用	安装结果
`libltc`	开源 LTC 编解码库，提供 C/C++ 程序调用的 API。	`libltc.so`、头文件和 `pkg-config` 配置文件。
`ltc-tools`	基于 `libltc` 的命令行工具集合。	源码目录下生成命令行程序。
`ltcdump`	从音频文件中读取并打印 LTC 时间码。	`ltc-tools/ltcdump` 可执行文件。

安装顺序必须是先安装 libltc，再编译 ltc-tools。如果系统没有找到 libsndfile，ltc-tools 可能仍能编译部分工具，但不会生成我们需要的 ltcdump。

三、准备编译环境

（一）确认系统和网络

先确认当前系统是 Rocky Linux（或CentOS），并确认服务器能够访问软件仓库和 GitHub：

复制代码

cat /etc/os-release
git --version
dnf --version
ping -c 3 github.com

如果服务器不能访问 GitHub，可以在联网机器上下载源码压缩包，再通过 U 盘、SCP 或内部文件服务器传到目标服务器。源码安装本身不要求必须使用 git clone。

（二）安装编译工具和依赖

以 root 用户执行：

复制代码

dnf groupinstall "Development Tools"
dnf install autoconf automake libtool pkgconf-pkg-config libsndfile-devel

Development Tools：提供 GCC、G++、Make 等基本编译工具。
autoconf、automake、libtool：生成和执行 GNU Autotools 构建流程。
pkgconf-pkg-config：让构建脚本找到已经安装的库和版本。
libsndfile-devel：提供读取 WAV 文件所需的头文件、库和 sndfile.pc。

权限提示：安装系统软件包和执行 make install 需要 root 权限。也可以普通用户编译，最后使用 sudo make install 安装。

四、编译安装 libltc

（一）为什么不用 dnf 直接安装

Rocky Linux 默认仓库中没有可直接安装的 libltc、ltc-tools 或 ltcdump 软件包。因此使用 dnf search 查不到它们是正常现象，不代表仓库损坏或命令写错，需要从官方源码仓库编译。

复制代码

dnf search libltc
dnf search ltc-tools
dnf search ltcdump

（二）下载 libltc 源码

复制代码

mkdir -p /usr/local/src
cd /usr/local/src
git clone https://github.com/x42/libltc.git
cd libltc

libltc 的上游项目是 x42/libltc。源码目录中应能看到 autogen.sh、configure.ac 等文件。

（三）运行 Autotools、编译并安装

复制代码

./autogen.sh
./configure --prefix=/usr/local
make -j$(nproc)
make install

--prefix=/usr/local 表示把库安装到系统的本地软件目录，避免覆盖发行版通过 dnf 安装的文件。安装完成后检查动态库、头文件和 pkg-config 文件：

复制代码

find /usr/local -name 'libltc.so*' -o -name 'ltc.h'
find /usr/local -name 'ltc.pc'

五、编译 ltc-tools

（一）更新动态库缓存

Rocky Linux 的动态链接器默认不一定搜索 /usr/local/lib 或 /usr/local/lib64。先根据实际安装位置配置动态库缓存：

复制代码

find /usr/local -name 'libltc.so*'

如果输出位于 /usr/local/lib：

复制代码

echo /usr/local/lib > /etc/ld.so.conf.d/libltc.conf
ldconfig

如果输出位于 /usr/local/lib64：

复制代码

echo /usr/local/lib64 > /etc/ld.so.conf.d/libltc.conf
ldconfig

确认动态链接器已经识别：

复制代码

ldconfig -p | grep libltc

（二）确认 pkg-config 能找到依赖

复制代码

pkg-config --modversion ltc
pkg-config --modversion sndfile

第一条命令应输出 libltc 的版本号，第二条命令应输出 libsndfile 的版本号。版本号不必固定，取决于源码和 Rocky Linux 仓库的当前版本。

如果 ltc.pc 已存在，但 pkg-config 仍提示找不到，可以临时补充搜索路径：

复制代码

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/local/lib64/pkgconfig:$PKG_CONFIG_PATH
pkg-config --modversion ltc

如果该路径要供 systemd 服务使用，需要在服务的 Environment= 中配置；只在当前终端执行 export，不会自动传给已经启动的服务。

（三）下载并编译 ltc-tools

复制代码

cd /usr/local/src
git clone https://github.com/x42/ltc-tools.git
cd ltc-tools
pkg-config --modversion ltc
pkg-config --modversion sndfile
make -j$(nproc)

ltc-tools 的构建要求 libltc 至少达到 1.3.2；当前源码版本可能输出更高版本号。在 libsndfile 可用时，Makefile 会构建 ltcdump 和 ltcgen 等工具。

六、验证 ltcdump

（一）检查文件和帮助信息

复制代码

cd /usr/local/src/ltc-tools
ls -l ltcdump
./ltcdump --help

正常情况下可以看到类似帮助信息：

复制代码

ltcdump - parse linear time code from a audio-file.

Usage: ltcdump [ OPTIONS ] <filename>

常用参数如下：

参数	作用
`-c`、`--channel`	选择音频通道。
`-f`、`--fps`	指定 LTC 帧率。
`-F`、`--detectfps`	尝试自动检测帧率。

默认解码第一个音频通道。对一个 WAV 文件进行测试：

复制代码

./ltcdump -F sample.wav

如果 WAV 文件中有质量足够的 LTC 信号，输出中应出现连续时间码。如果只看到错误或没有时间码，还需要检查音频通道、采样率、录音电平和帧率设置。

（二）检查程序的动态库依赖

复制代码

ldd ./ltcdump | grep -E 'ltc|sndfile|not found'

输出中不应出现 not found。如果出现，说明编译完成但运行时动态链接器找不到某个库，应回到动态库缓存或 LD_LIBRARY_PATH 配置步骤处理。

七、过程中遇到的问题与解决方法

问题 1：dnf 找不到 libltc、ltc-tools 或 ltcdump

现象：执行 dnf search 没有结果，或安装命令提示没有匹配的软件包。

原因：Rocky Linux 默认仓库没有这些目标软件包；ltcdump 还是源码项目中的构建产物，不是独立包名。

解决：安装编译环境后，从官方 Git 仓库获取 libltc 和 ltc-tools 源码。

问题 2：ltc-tools 编译后没有 ltcdump

现象：执行 make 后目录中没有 ltcdump。

原因：ltcdump 需要 libsndfile 读取 WAV 文件；只有运行时库不够，还需要开发包中的头文件和 pkg-config 配置。

解决：安装 libsndfile-devel，确认依赖有版本输出，然后在 ltc-tools 目录重新执行：

复制代码

pkg-config --modversion ltc
pkg-config --modversion sndfile
make clean
make -j$(nproc)

问题 3：pkg-config 找不到 ltc

现象：提示类似 Package ltc was not found in the pkg-config search path。

原因：libltc 安装到了 /usr/local/lib/pkgconfig 或 /usr/local/lib64/pkgconfig，但当前环境没有搜索该目录。

解决：

复制代码

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/local/lib64/pkgconfig:$PKG_CONFIG_PATH
pkg-config --modversion ltc

长期运行的 systemd 服务还需要单独配置环境变量，不能只依赖当前 shell 的 export。

问题 4：运行 ltcdump 时提示 libltc.so 找不到

现象：执行 ./ltcdump --help 时提示 error while loading shared libraries: libltc.so。

原因：库已经安装，但动态链接器缓存没有更新，或安装目录不在系统默认搜索路径中。

解决：确认实际路径后执行：

复制代码

find /usr/local -name 'libltc.so*'
echo /usr/local/lib > /etc/ld.so.conf.d/libltc.conf
ldconfig
ldconfig -p | grep libltc

如果实际路径是 /usr/local/lib64，将上面的目录替换为 /usr/local/lib64。也可以临时验证：

复制代码

LD_LIBRARY_PATH=/usr/local/lib:/usr/local/lib64:$LD_LIBRARY_PATH ./ltcdump --help

问题 5：configure 或 autogen.sh 执行失败

现象：提示找不到 autoreconf、aclocal、libtoolize，或提示没有 configure。

原因：Autotools 工具没有安装，或源码仓库没有完整下载。

解决：

复制代码

dnf install autoconf automake libtool pkgconf-pkg-config
command -v autoreconf aclocal libtoolize
cd /usr/local/src/libltc
./autogen.sh

如果源码下载不完整，应重新下载完整源码，或在联网机器下载源码压缩包后传输到目标服务器。不建议在没有完整错误信息的情况下手工创建 configure 文件。

问题 6：ltcdump 能运行，但没有输出时间码

现象：程序启动正常，但没有解析出连续时间码。

原因：这通常不是安装问题，可能是 LTC 不在默认的第一个音频通道，或音频信号质量、帧率和采样参数不匹配。

排查：

复制代码

./ltcdump --help
./ltcdump -c 1 -F sample.wav
./ltcdump -c 2 -F sample.wav

还应确认 WAV 文件确实包含 LTC 音频，而不是普通节目音频；检查左右声道、录音电平、采样率以及 LTC 发生器使用的帧率。

不要混淆："ltcdump 命令能启动"只能说明程序和动态库安装正确，不能证明输入 WAV 中一定存在可用的 LTC 信号。

八、完整命令清单

下面是一套从零开始的连续命令，适合在新 Rocky Linux 主机上执行：

复制代码

dnf groupinstall "Development Tools"
dnf install autoconf automake libtool pkgconf-pkg-config libsndfile-devel

mkdir -p /usr/local/src
cd /usr/local/src
git clone https://github.com/x42/libltc.git
cd libltc
./autogen.sh
./configure --prefix=/usr/local
make -j$(nproc)
make install

find /usr/local -name 'libltc.so*'
# 根据 find 的结果二选一：
echo /usr/local/lib > /etc/ld.so.conf.d/libltc.conf
# 或：echo /usr/local/lib64 > /etc/ld.so.conf.d/libltc.conf
ldconfig

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/local/lib64/pkgconfig:$PKG_CONFIG_PATH
pkg-config --modversion ltc
ldconfig -p | grep libltc

cd /usr/local/src
git clone https://github.com/x42/ltc-tools.git
cd ltc-tools
pkg-config --modversion ltc
pkg-config --modversion sndfile
make -j$(nproc)

ls -l ltcdump
./ltcdump --help
ldd ./ltcdump | grep -E 'ltc|sndfile|not found'

动态库目录只能根据实际的 find 结果选择，不能盲目假设一定是 /usr/local/lib 或一定是 /usr/local/lib64。

九、安装完成后的文件位置

内容	常见位置
ltc-tools 源码	`/usr/local/src/ltc-tools`
ltcdump 可执行文件	`/usr/local/src/ltc-tools/ltcdump`
libltc 动态库	`/usr/local/lib/libltc.so` 或 `/usr/local/lib64/libltc.so`
libltc 头文件	`/usr/local/include/ltc.h` 或相近的 include 子目录
pkg-config 文件	`/usr/local/lib/pkgconfig/ltc.pc` 或 `/usr/local/lib64/pkgconfig/ltc.pc`

如果后续要在 C++ 项目中使用 libltc，应通过头文件和库链接它，而不是通过启动 ltcdump 读取输出。ltcdump 更适合安装验证、WAV 文件排查和现场问题定位。