GStreamer/gstreamer

# GStreamer 这是 GStreamer，一个流媒体框架。 ## 从这里开始 我们的网站位于 https://gstreamer.freedesktop.org 我们的文档，包括教程、API 参考和常见问题解答 (FAQ) 可以在以下地址找到 https://gstreamer.freedesktop.org/documentation/ 您可以在 GStreamer Discourse 上提问 https://discourse.gstreamer.org/ 我们在 GitLab 中跟踪错误、功能请求和合并请求（补丁） https://gitlab.freedesktop.org/gstreamer/ 您可以加入我们的 Matrix 聊天室 https://matrix.to/#/#gstreamer:gstreamer.org 此仓库包含 GStreamer 社区支持的所有官方模块，这些模块可以在 `subprojects/` 目录中找到。 ## 入门指南 ### 安装 git 和 python 3.8+ 如果您使用的是 Linux，您可能已经安装了这些工具。在 macOS 上，新版本的 Xcode 已经附带了 Python 3。如果您使用的是旧版 Xcode，可以使用 [官方 Python 安装程序](https://www.python.org/downloads/mac-osx/)。 您可以找到 [适用于 Windows 的说明](#windows-prerequisites-setup)。 ### 安装 meson 和 ninja 需要 Meson 1.1 或更新版本。 在 Linux 和 macOS 上，您可以通过包管理器获取 meson，或者使用： ``` $ pip3 install --user meson ``` 这会将 meson 安装到 `~/.local/bin`，该路径默认情况下可能会也可能不会自动包含在您的 PATH 中。 您应该使用包管理器获取 `ninja`，或者下载 [官方发布版](https://github.com/ninja-build/ninja/releases) 并将 `ninja` 二进制文件放入您的 PATH 中。 您可以找到 [适用于 Windows 的说明](#windows-prerequisites-setup)。 如果您在 macOS 上使用的是官方 Python 安装程序，而不是 Xcode 附带的 Python 3，您可能需要从用户 Applications 文件夹中的 Python 文件夹执行“Install Certificates.command”： ``` $ /Applications/Python\ 3.*/Install\ Certificates.command ``` 否则，在下载 meson wraps 时会出现此错误： ``` urllib.error.URLError: urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed ``` ### 构建 GStreamer 及其模块 您可以通过运行以下命令来构建所有 GStreamer： ``` meson setup builddir meson compile -C builddir ``` 这将自动创建 `builddir` 目录并在其中构建所有内容。 注意：在 Windows 上，如果 `PATH` 中没有 GCC、clang 等，meson 将自动检测并使用最新的 Visual Studio。使用 `--vsenv` 参数可强制使用 Visual Studio。 注意：一旦子项目被获取，Meson 不会自动更新子项目。如果 wrap 文件已更新，请记得更新子项目。 ``` meson subprojects update ``` ### 外部依赖 GStreamer 的所有强制依赖项都作为 [meson 子项目](https://mesonbuild.com/Subprojects.html) 包含在内：libintl、zlib、libffi、glib。一些可选依赖项也作为子项目包含在内，例如 ffmpeg、x264、json-glib、graphene、openh264、orc 等。 如果 meson 无法使用 pkg-config 在您的系统中找到强制依赖项，它们将被自动构建。作为子项目包含的可选依赖项也是如此。您可以通过查看 `subprojects` 目录找到完整列表。 需要未包含的可选依赖项的插件只能在系统提供这些依赖项的情况下构建。下面列出了如何构建一些常见依赖项（如 Qt5/QML）的说明。如果您不知道如何提供插件所需的可选依赖项，应该使用 [Cerbero](https://gitlab.freedesktop.org/gstreamer/cerbero/#description)，它会自动为您处理此事。 如果可能，插件将被自动启用，但您可以通过启用包含它的 gstreamer 仓库及其内部的插件，来确保构建特定的插件（尤其是具有外部依赖项的插件）。例如，要在 gst-plugins-good 仓库中启用 Qt5 插件，您需要按如下方式运行 meson： ``` meson -Dgood=enabled -Dgst-plugins-good:qt5=enabled builddir ``` 如果插件无法启用，这将导致 Meson 报错退出。您也可以翻转默认值，禁用除显式启用的插件之外的所有插件，如下所示： ``` meson -Dauto_features=disabled -Dgstreamer:tools=enabled -Dbad=enabled -Dgst-plugins-bad:openh264=enabled ``` 这将禁用所有可选功能，然后启用 `openh264` 插件和核心 gstreamer 仓库附带的工具：`gst-inspect-1.0`、`gst-launch-1.0` 等。照例，您可以在已设置的 builddir 上使用 `meson configure -Doption=value` 更改这些值。 ### 构建 Qt5 QML 插件 如果 `qmake` 不在 `PATH` 中且 pkgconfig 文件不可用，您可以在运行上述 `meson` 之前，将 `QMAKE` 环境变量指向您选择的 Qt5 安装路径。 如果可能，插件将被自动启用，但您可以通过向 `meson` 传递 `-Dgood=enabled -Dgst-plugins-good:qt5=enabled` 来确保构建它。 ### 构建 Intel MSDK 插件 在 Linux 上，您需要安装 `libmfx` 的开发文件。在 Windows 上，如果您安装了 [Intel Media SDK](https://software.intel.com/en-us/media-sdk)，它将设置 `INTELMEDIASDKROOT` 环境变量，构建文件将使用该变量来查找 `libmfx`。 如果可能，插件将被自动启用，但您可以通过向 `meson` 传递 `-Dbad=enabled -Dgst-plugins-bad:msdk=enabled` 来确保启用它。 ### 构建带有 (A)GPL 许可依赖项的插件 某些插件具有 GPL 或 AGPL 许可的依赖项，只有在您通过向 Meson 传递 `-Dgpl=enabled` 显式选择允许 (A)GPL 许可的依赖项时，才会构建这些插件。 gst-plugins-bad 中具有 (A)GPL 许可依赖项的插件列表（非详尽）： - dts (DTS 音频解码器插件) - faad (Free AAC 音频解码器插件) - iqa (基于 dssim-c 的图像质量评估插件) - mpeg2enc (MPEG-2 视频编码器插件) - mplex (音频/视频复用器插件) - ofa (Open Fingerprint Architecture 库插件) - resindvd (Resin DVD 播放插件) - x265 (HEVC/H.265 视频编码器插件) gst-plugins-ugly 中具有 (A)GPL 许可依赖项的插件列表（非详尽）： - a52dec (Dolby Digital (AC-3) 音频解码器插件) - cdio (基于 libcdio 的 CD 音频源插件) - dvdread (基于 libdvdread 的 DVD 视频源插件) - mpeg2dec (基于 libmpeg2 的 MPEG-2 视频解码器插件) - sidplay (基于 libsidplay 的 Commodore 64 音频解码器插件) - x264 (基于 libx264 的 H.264 视频编码器插件) ### 静态构建 自 *1.18.0* 起，当使用 `--default-library=static` 进行静态构建时，将生成一个共享库 `gstreamer-full-1.0` 以及一个包配置文件，其中包含所有已启用的 GStreamer 插件和库。 可以使用 `gst-full-libraries` 选项设置需要在 `gstreamer-full-1.0` ABI 中暴露的库列表。 glib-2.0、gobject-2.0 和 gstreamer-1.0 始终包含在内。 ``` meson setup --default-library=static -Dgst-full-libraries=gstreamer-app-1.0,gstreamer-video-1.0 builddir ``` GStreamer *1.18* 要求使用 gstreamer-full-1.0 的应用程序在 `gst_init()` 之后调用 `gst_init_static_plugins()` 来初始化静态插件。该函数在 `gst/gstinitstaticplugins.h` 头文件中定义。 自 *1.20.0* 起，`gst_init_static_plugins()` 将由 `gst_init()` 自动调用，应用程序不再需要手动调用它。 该头文件已从公共 API 中移除。 可以使用 `gst-full-version-script` 选项将 [版本脚本](https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html) 传递给链接器。这可用于控制 `gstreamer-full` 库导出的确切符号，允许链接器回收未使用的代码，从而减少库的总大小。默认脚本 `gstreamer-full-default.map` 仅将 glib/gstreamer 符号声明为公共符号。 可以使用 `gst-full-plugins` 选项传递要在 `gstreamer-full` 库中注册的插件列表。默认值为 '*'，这意味着在构建过程中选择的所有插件都将被静态注册。 空值将阻止注册任何插件。 可以使用 `gst-full-elements`、`gst-full-typefind-functions`、`gst-full-device-providers` 或 `gst-full-dynamic-types` 选择特定的功能集，以便从插件中选择特定功能。 当某个功能列在这些选项之一时，即使该插件列在 `gst-full-plugins` 中，其插件中的其他功能也不再自动包含。 用户必须确保在构建配置期间启用了所有选定的插件和功能（element、typefind 等）。 要注册功能，语法如下：插件以 ';' 分隔，插件中的功能以 ':' 开始，并以 ',' 分隔。 例如： * `-Dgst-full-plugins=coreelements;typefindfunctions;alsa;pbtypes`： 仅启用 `coreelements`、`typefindfunctions`、`alsa`、`pbtypes` 插件。 * `-Dgst-full-elements=coreelements:filesrc,fakesink,identity;alsa:alsasrc`： 仅启用 `coreelements` 插件中的 `filesrc`、`identity` 和 `fakesink` 元素，以及 `alsa` 插件中的 `alsasrc` 元素。 * `-Dgst-full-typefind-functions=typefindfunctions:wav,flv`： 仅启用 `typefindfunctions` 中的 `wav` 和 `flv` typefind 功能 * `-Dgst-full-device-providers=alsa:alsadeviceprovider`： 从 `alsa` 插件启用 `alsadeviceprovider`。 * `-Dgst-full-dynamic-types=pbtypes:video_multiview_flagset`： 从 `pbtypes` 启用 `video_multiview_flagset`。 `playback` 插件中的所有功能将被启用，其他插件将限制为请求的特定功能。 所有选定的功能将注册到专用的 `NULL` 插件名称中。 这将导致未注册的功能/插件不包含在最终的 gstreamer-full 库中。 这是一个实验性功能，未来仍可能进行不向后兼容的更改。 目前仅对类 Linux 平台提供良好支持，而 Windows、MSVC 和 MinGW 应被视为 *实验性*，因为符号导出问题仍在讨论中。 自 1.24.7 起，可以通过传递 `-Dgst-full=disabled` 来禁用 `gstreamer-full` 库。这对于您想要静态构建 gstreamer 但不想使用 gst-full 的情况很有用，因为链接与其关联的静态可执行文件可能会非常消耗 CPU/RAM。 #### 完全静态构建 自 *1.24.0* 起，还可以将应用程序与 GStreamer 静态链接。这意味着所有 gstreamer 库都将链接到您的库或应用程序中。但是，需要注意的是，即使 `gstreamer-full` 库可以静态构建到应用程序中，它也不包含所有代码（核心库和插件）。 相反，它依赖于所有其他静态库。因此，虽然 `gstreamer-full` 库提供了一个统一的访问点，但实际功能分布在各种静态库中。 您可以使用 `-Dgst-full-target-type=static_library` 启用此选项，该选项默认设置为 `shared_library`。构建系统将根据您如上所述的 `gstreamer-full` 配置生成一组归档文件。 您的应用程序现在可以在 meson 中或通过包配置文件检查 `gstreamer-full` 依赖项。 在这两种情况下，应用程序都可以依赖构建过程中生成的 `gstreamer-full-1.0.pc` 文件来检索其所有依赖项。 在该配置中，在构建配置期间选择的功能将在调用 `gst_init()` 期间自动注册。 ### 构建文档 默认情况下不构建文档，因为生成速度较慢。要构建文档，首先确保已安装 `hotdoc` 并启用了 `doc` 选项。对于 API 文档，还必须启用 gobject introspection。 然后可以使用特殊目标 `gst-doc` 来（重新）生成文档。 ``` $ pip install hotdoc $ meson setup -Ddoc=enabled -Dintrospection=enabled builddir $ meson compile -C builddir gst-doc ``` 注意：要可视化文档，可以在开发环境（见下文）中运行 `devhelp`。 # 开发环境 ## 开发环境目标 GStreamer 使用 [Meson devenv](https://mesonbuild.com/Commands.html#devenv) 让您进入一个开发环境，其中您刚刚构建的所有插件、库和工具都可用： ``` meson devenv -C ``` 或者，如果您不想在工作流程中启动 shell，可以将当前环境转变为合适的状态，如下所示： ``` meson devenv -C --dump ``` 这将打印适合 sh 兼容 `eval` 函数的输出，就像 `ssh-agent -s` 一样。 可以使用以下命令在开发环境中运行外部脚本： ``` meson devenv -C external_script.sh ``` 注意：在开发环境中，一个完全可用的前缀也在 `gstreamer/prefix` 中配置好了，您可以在那里安装任何额外的依赖项/项目。 有关开发环境的更详细文档，请访问 [文档](https://gstreamer.freedesktop.org/documentation/installing/building-from-source-using-meson.html)。 ## Windows 开发环境 ### 前置条件 - **Visual Studio Community 2022**（或更高版本），包含： - 使用 C++ 的桌面开发工作负载 - Windows SDK - **Python 3.8+**（构建系统和 gst-env.py 需要） - **Meson 0.59.0+**（通过 pip 安装：`pip install meson`） 建议使用 Visual Studio Community 2 和 PowerShell 终端。 当未找到其他编译器时，Meson 0.59.0+ 会自动检测并激活 Visual Studio 工具链。为了获得完整的用户体验，应在 PowerShell 环境中构建 GStreamer。 注意：如果您的 PATH 中有其他工具链（MinGW、Clang 等），Meson 可能会检测到它们而不是 Visual Studio。为确保使用 Visual Studio： - 从 Windows PATH 中移除冲突的工具链，或 - 使用 `--vsenv` 标志：`meson setup --vsenv builddir`，或 - 从预配置环境的 Developer PowerShell for VS 2022 运行 ### 使用 Visual Studio 构建 ``` meson setup builddir meson compile -C builddir ``` 注意：您应该验证是否检测到了 Visual Studio。查找类似于以下内容的输出： ``` ... Activating VS 17.x.x ... ``` ### 在 PowerShell 中使用开发环境 ``` python.exe gst-env.py ``` 或使用自定义构建目录： ``` python.exe gst-env.py --builddir builddir ``` 您也可以直接使用 ninja： ``` ninja -C builddir devenv ``` 开发环境将配置所有必要的路径（PATH、GST_PLUGIN_PATH 等），以便您可以立即使用 GStreamer 工具并测试您的更改： ``` gst-inspect-1.0.exe coreelements gst-launch-1.0.exe videotestsrc ! autovideosink ``` ## 自定义子项目 我们还添加了一个 meson 选项 `custom_subprojects`，允许用户提供一个以逗号分隔的 meson 子项目列表，这些子项目应与默认子项目一起构建。 要使用它： ``` # 克隆到 subprojects 目录 $ git -C subprojects clone my_subproject # 清除依赖检测状态，以防您已有现有的 build dir $ meson setup --wipe builddir -Dcustom_subprojects=my_subproject $ meson compile -C builddir ``` ## 运行测试 您可以轻松运行所有组件的测试： ``` meson test -C builddir ``` 列出所有可用的测试： ``` meson test -C builddir --list ``` 运行特定组件的所有测试： ``` meson test -C builddir --suite gst-plugins-base ``` 或运行特定的测试文件： ``` meson test -C builddir --suite gstreamer gst_gstbuffer ``` 从特定测试文件运行特定测试： ``` GST_CHECKS=test_subbuffer meson test -C builddir --suite gstreamer gst_gstbuffer ``` ## 可选安装 您还可以将构建的所有内容安装到预定的前缀中，如下所示： ``` meson setup --prefix=/path/to/install/prefix builddir meson compile -C builddir meson install -C builddir ``` 请注意，安装的文件已剥离 `RPATH`，因此您需要根据您的平台设置 `LD_LIBRARY_PATH`、`DYLD_LIBRARY_PATH` 或 `PATH` 才能正常运行。 ## 在提示行中添加 GStreamer 开发环境信息 ### Bash 提示符 我们会自动处理 `bash` 并相应地设置 `$PS1`。 如果不希望自动覆盖 `$PS1`（可能您有一个精美的自定义提示符），请将 `$GST_BUILD_DISABLE_PS1_OVERRIDE` 环境变量设置为 `TRUE`，并在设置自定义提示符时使用 `$GST_ENV`，例如使用以下代码片段： ``` ... if [[ -n "${GST_ENV-}" ]]; then PS1+="[ ${GST_ENV} ]" fi ... ``` ### 使用 powerline 在您的 powerline 主题配置文件中（默认位于 `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`），您应该添加一个新的环境段，如下所示： ``` { "function": "powerline.segments.common.env.environment", "args": { "variable": "GST_ENV" }, "priority": 50 }, ``` ## Windows 前置条件设置 在 Windows 上，某些组件可能需要特别注意。 ### Git for Windows 使用 [Git for Windows](https://gitforwindows.org/) 安装程序。它将安装一个带有基本 shell 工具和最新 git 二进制文件的 `bash` 提示符。 在安装过程中，当提示关于 `PATH` 时，您应该选择以下选项：  ### Windows 上的 Python 3.8+ 使用 [官方 Python 安装程序](https://www.python.org/downloads/windows/)。 您必须确保 Python 安装到 `PATH` 中：  您可能还想自定义安装并将其安装到系统范围的位置（如 `C:\PythonXY`），但这不是必需的。 ### Windows 上的 Ninja 如果您使用的是 Visual Studio 2019 或更新版本，则已提供 Ninja。 在其他情况下，在 Windows 上安装 Ninja 的最简单方法是使用 `pip3`，它将下载编译后的二进制文件并将其放入 Python 安装目录内的 `Scripts` 目录中： ``` pip3 install ninja ``` 您也可以下载 [官方发布版](https://github.com/ninja-build/ninja/releases) 并将其放入 `PATH` 中，或使用 MSYS2。 ### Windows 上的 Meson **重要**：不要使用 Meson MSI 安装程序，因为它是实验性的，已知无法与 `GStreamer` 一起使用。 您可以使用 `pip3` 安装 Meson，与上面的 Ninja 相同： ``` pip3 install meson ``` 请注意，Meson 完全是用 Python 编写的，因此如果您出于某种原因想使用最新的 master 分支，也可以直接从 [git 仓库](https://github.com/mesonbuild/meson/) 运行它。 ### 在 Windows 上运行 Meson 自 0.59.0 版本起，如果在 Windows 上未找到其他编译器（gcc、clang 等），Meson 会自动激活 Visual Studio 环境。要在这种情况下强制使用 Visual Studio，您可以使用： ``` meson setup --vsenv builddir ``` ### 在 linux 上设置基于 mingw/wine 的开发环境 #### 安装 wine 和 mingw ##### 在 fedora x64 上 ``` sudo dnf install mingw64-gcc mingw64-gcc-c++ mingw64-pkg-config mingw64-winpthreads wine ``` FIXME：弄清楚在其他发行版上需要安装什么 #### 从 git 获取 meson 这简化了流程，并允许我们使用 meson 本身定义的跨文件。 ``` git clone https://github.com/mesonbuild/meson.git ``` #### 构建和安装 ``` BUILDDIR=$PWD/winebuild/ export WINEPREFIX=$BUILDDIR/wine-prefix/ && mkdir -p $WINEPREFIX # 设置 prefix 是强制性的，因为它用于在开发环境中设置 symlinks meson/meson.py $BUILDDIR --cross-file meson/cross/linux-mingw-w64-64bit.txt -Dgst-plugins-bad:vulkan=disabled -Dorc:gtk_doc=disabled --prefix=$BUILDDIR/wininstall/ -Djson-glib:gtk_doc=disabled meson/meson.py install -C $BUILDDIR/ ``` 或者，您也可以在 Fedora 上使用 `mingw64-meson`，这是一个包装脚本，用于设置使用 Fedora 的跨文件和设置。但是，该包装脚本在某些情况下可能存在错误。 #### cross-mingw 开发环境 您可以按照[上面](#development-environment)描述的方式进入开发环境。 在设置 [binfmt] 使用 wine 运行 windows 二进制文件后，您可以通过运行以下命令在 wine 下运行 GStreamer 工具： ``` gst-launch-1.0.exe videotestsrc ! glimagesink ``` #### vscode 集成 一个名为 `.vscode/launch.json.sample` 的文件可用作调试和运行 GStreamer 应用程序（如 `gst-launch-1.0`）的参考。您只需将该文件复制到 `.vscode/launch.json` 即可在 Visual Studio Code 中启用调试会话。

标签：FOSS, GStreamer, Meson, Ninja, 云安全, 多媒体, 多媒体基础设施, 多媒体开发, 多媒体引擎, 多媒体框架, 客户端加密, 客户端加密, 嵌入式, 开源, 插件, 流媒体, 渲染, 管道, 编码, 编解码器, 视频, 视频流, 解码, 转码, 逆向工具, 音视频处理, 音频, 音频流, 预握手