2021 gstreamer插件编写指南中英对照 (一) 前言

Introduction 介绍

GStreamer is an extremely powerful and versatile framework for creating streaming media applications. Many of the virtues of the GStreamer framework come from its modularity: GStreamer can seamlessly incorporate new plugin modules. But because modularity and power often come at a cost of greater complexity (consider, for example, CORBA), writing new plugins is not always easy.
GStreamer是一个非常强大和通用的框架，用于创建流媒体应用程序。GStreamer框架的许多优点来自于它的模块化:GStreamer可以无缝地合并新的插件模块。但是，由于模块化和强大的功能通常以更大的复杂性为代价(例如，考虑CORBA)，编写新插件并不容易。
This guide is intended to help you understand the GStreamer framework so you can develop new plugins to extend the existing functionality. The guide addresses most issues by following the development of an example plugin - an audio filter plugin - written in C. However, the later parts of the guide also present some issues involved in writing other types of plugins, and the end of the guide describes some of the Python bindings for GStreamer.
本指南旨在帮助您理解GStreamer框架，以便您可以开发新的插件来扩展现有的功能。本指南通过一个C语言编写的音频过滤器插件，来阐述与之相关的很多问题。当然，指南后续涉及到其他类型的插件编写的时候，也还存在一些问题。最后，指南描述了一些关于在GStreamer 进行Python绑定的内容。

Preface 前言

What is GStreamer? GStreamer是啥？

GStreamer is a framework for creating streaming media applications. The fundamental design comes from the video pipeline at Oregon Graduate Institute, as well as some ideas from DirectShow.
GStreamer是一个用于创建流媒体应用程序的框架。基本设计源自俄勒冈研究生院的视频管道的思路，以及DirectShow的一些构想。
GStreamer’s development framework makes it possible to write any type of streaming multimedia application. The GStreamer framework is designed to make it easy to write applications that handle audio or video or both. It isn’t restricted to audio and video, and can process any kind of data flow. The pipeline design is made to have little overhead above what the applied filters induce. This makes GStreamer a good framework for designing even high-end audio applications which put high demands on latency or performance.
GStreamer的开发框架，能够编写任何类型的流媒体应用程序。GStreamer框架旨在很容易地编写处理音频或视频，或两者都处理的应用程序。它不局限于音频和视频，可以处理任何其它类型的数据流。管道设计的开销要比应用过滤器产生的开销小，这使得GStreamer成为针对延迟或性能有很高要求的、高端音频应用程序的框架。
One of the most obvious uses of GStreamer is using it to build a media player. GStreamer already includes components for building a media player that can support a very wide variety of formats, including MP3, Ogg/Vorbis, MPEG-1/2, AVI, Quicktime, mod, and more.
GStreamer最明显的用法之一是使用它来构建媒体播放器。GStreamer已经包含了用于构建媒体播放器的组件，它可以支持非常广泛的格式，包括MP3、Ogg/Vorbis、MPEG-1/2、AVI、Quicktime、mod等。
GStreamer, however, is much more than just another media player. Its main advantages are that the pluggable components can be mixed and matched into arbitrary pipelines so that it’s possible to write a full-fledged video or audio editing application.
当然，GStreamer不仅仅是一款媒体播放器。它的主要优点是可以将插件化的部件，混合并匹配到任意管道中，这样就可以编写一个完整的视频或音频编辑应用程序。
The framework is based on plugins that will provide the various codec and other functionality. The plugins can be linked and arranged in a pipeline. This pipeline defines the flow of the data.
该框架基于提供各种编解码器和其他功能的插件。这些插件可以在管道中排列并链接到一起，管道定义了数据流向。
The GStreamer core function is to provide a framework for plugins, data flow, synchronization and media type handling/negotiation. It also provides an API to write applications using the various plugins.
GStreamer的核心功能是为插件、数据流、同步和媒体类型处理/协商等，提供一个框架。它还提供了使用各种插件编写应用程序的API。

Who Should Read This Guide? 哪些人需要阅读本指南？

This guide explains how to write new modules for GStreamer. The guide is relevant to several groups of people:
本指南解释了如何为GStreamer编写新模块。该指南适用于以下几类人群:

• Anyone who wants to add support for new ways of processing data in GStreamer. For example, a person in this group might want to create a new data format converter, a new visualization tool, or a new decoder or encoder.
  想要在GStreamer中添加新的数据处理方式的人。例如，该组中的人员可能希望创建新的数据格式转换器、新的可视化工具或新的解码器或编码器。

• Anyone who wants to add support for new input and output devices. For example, people in this group might want to add the ability to write to a new video output system or read data from a digital camera or special microphone.
  想要添加新的输入和输出设备的人。例如，在视频输出系统添加写入的能力，或想从数码相机或特殊麦克风添加数据读取功能等。

• Anyone who wants to extend GStreamer in any way. You need to have an understanding of how the plugin system works before you can understand the constraints that the plugin system places on the rest of the code. Also, you might be surprised after reading this at how much can be done with plugins.
  想以任何方式扩展GStreamer的人。在理解插件系统对其余代码的约束之前，您需要先了解插件系统是如何工作的。此外，你可能会在阅读这篇文章后，对插件可以做多少事情感到惊讶。
  This guide is not relevant to you if you only want to use the existing functionality of GStreamer, or if you just want to use an application that uses GStreamer.
  如果您只想使用GStreamer的现有功能，或者只想使用GStreamer的应用程序，那么你没有必要阅读这份文档。
  If you are only interested in using existing plugins to write a new application - and there are quite a lot of plugins already - you might want to check the GStreamer Application Development Manual. 如果您只对使用现有的插件来编写新的应用程序感兴趣——本来已经有相当多的插件了——您应该去看《GStreamer应用程序开发手册》。
  If you are just trying to get help with a GStreamer application, then you should check with the user manual for that particular application.如果您只是想获得关于某特定的GStreamer应用程序的帮助，那么您应该查看该特定应用程序的用户手册。

Preliminary Reading 预先阅读

This guide assumes that you are somewhat familiar with the basic workings of GStreamer. For a gentle introduction to programming concepts in GStreamer, you may wish to read the GStreamer Application Development Manual first. Also check out the other documentation available on the GStreamer web site.
在阅读本指南之前，您需要先对GStreamer的基本工作原理有所熟悉。建议您先阅读《GStreamer应用程序开发手册》，以及GStreamer网站上提供的其他文档，了解GStreamer编程的相关基础概念。
In order to understand this manual, you will need to have a basic understanding of the C language. Since GStreamer adheres to the GObject programming model, this guide also assumes that you understand the basics of GObject programming. You may also want to have a look at Eric Harlow’s book Developing Linux Applications with GTK+ and GDK.为了理解本手册，您需要对C语言有一个基本的了解。由于GStreamer遵循GObject编程模型，因此本指南还假设您理解GObject编程的基础知识。您还可以看看Eric Harlow的书《用GTK+和GDK开发Linux应用程序》。

Structure of This Guide文档结构

To help you navigate through this guide, it is divided into several large parts. Each part addresses a particular broad topic concerning GStreamer plugin development. The parts of this guide are laid out in the following order:
为了帮助您浏览本指南，本文分为几个大的部分。每一部分都涉及一个GStreamer插件开发的特定主题。各部分的排列顺序如下:

• Building a Plugin - Introduction to the structure of a plugin, using an example audio filter for illustration.
  构建一个插件：介绍一个插件的结构，用一个音频滤波器的例子来说明。
  This part covers all the basic steps you generally need to perform to build a plugin, such as registering the element with GStreamer and setting up the basics so it can receive data from and send data to neighbour elements.
  本部分涵盖了构建插件通常需要执行的所有基本步骤，比如向GStreamer注册元素，以及设置基本内容，以便它可以从邻近的元素接收数据和发送数据。The discussion begins by giving examples of generating the basic structures and registering an element in Constructing the Boilerplate. 首先给出一个示例，阐述了在一个构建的样本中注册元素，生成基本的结构。
  Then, you will learn how to write the code to get a basic filter plugin working in Specifying the pads, The chain function and What are states?然后，您将学习如何编写代码，以获得一个基本的过滤器插件，它工作在指定pads，并了解链函数和状态的含义。
  After that, we will show some of the GObject concepts on how to make an element configurable for applications and how to do application-element interaction in Adding Properties and Signals. 之后，我们将展示一些关于如何使一个元素为应用程序可配置的GObject概念，以及如何在添加属性和信号中进行应用程序-元素交互。
  Next, you will learn to build a quick test application to test all that you’ve just learned in Building a Test Application. We will just touch upon basics here. For full-blown application development, you should look at the Application Development Manual.
  接下来，您将学习如何构建一个快速测试应用程序，并测试您在构建测试应用程序中，学到的所有内容。我们在这里只讨论一些基本知识。对于成熟的应用程序开发，您应该查看应用程序开发手册。
• Advanced Filter Concepts - Information on advanced features of GStreamer plugin development.
  高级过滤器概念——关于GStreamer插件开发的高级特性的信息。
  After learning about the basic steps, you should be able to create a functional audio or video filter plugin with some nice features. However, GStreamer offers more for plugin writers.
  在学习了基本步骤之后，你应该能够创建一个性能优异的音频或视频过滤插件。当然，GStreamer为插件编写人员提供了更多的东西。
  This part of the guide includes chapters on more advanced topics, such as scheduling, media type definitions in GStreamer, clocks, interfaces and tagging. Since these features are purpose-specific, you can read them in any order, most of them don’t require knowledge from other sections.这一部分指南包括关于更高级的主题，如调度、媒体类型定义、时钟、接口和标签。因为这些特性是用于特定目的，他们之间没有啥关联，所以您不需要顺序阅读。
  The first chapter, named Different scheduling modes, will explain some of the basics of element scheduling. It is not very in-depth, but is mostly some sort of an introduction on why other things work as they do. Read this chapter if you’re interested in GStreamer internals.
  第一章，叫做不同的调度模式，会解释一些元素调度的基础知识。它并不深入，主要是介绍它们的运行方式。如果你对GStreamer 内部比较感兴趣可以看看。Next, we will apply this knowledge and discuss another type of data transmission than what you learned in The chain function: Different scheduling modes.Loop-based elements will give you more control over input rate. This is useful when writing, for example, muxers or demuxers.
  之后，我们应用这些知识，并讨论这在本章学到的另一种类型的数据传输功能：差异调度模式。 基于循环的元素可以让你更好地控制输入速率。这在编写muxer或demuxer时很有用。
  Next, we will discuss media identification in GStreamer in Media Types and Properties. You will learn how to define new media types and get to know a list of standard media types defined in GStreamer.
  接下来，我们将在媒体类型和属性中，讨论GStreamer中的媒体标识。您将学习如何定义新的媒体类型，并了解在GStreamer中定义的标准媒体类型列表。
  The next chapter, Clocking, will explain the concept of clocks in GStreamer. You need this information when you want to know how elements should achieve audio/video synchronization.下一章是时钟，将解释GStreamer时钟的概念。当您想知道元素应该如何实现音频/视频同步时，您需要这些信息。
  The next few chapters will discuss advanced ways of doing application-element interaction. Previously, we learned on the GObject-ways of doing this in Adding Properties and Signals. We will discuss dynamic parameters, which are a way of defining element behaviour over time in advance, in Supporting Dynamic Parameters.
  接下来的几章将讨论进行应用程序元素交互的高级方式。在前面，我们将学习通过GObject添加属性和信号的方法。我们将阐述动态参数，这是一种提前定义元素行为的方法。
  Next, you will learn about interfaces in Interfaces. Interfaces are very target- specific ways of application-element interaction, based on GObject’s GInterface. Lastly, you will learn about how metadata is handled in GStreamer in Tagging (Metadata and Streaminfo).
  接下来，您将学习Interfaces。Interfaces 是基于GObject的GInterface，用于特定目标的应用程序-元素交互的方式。最后，您将了解在GStreamer标签(元数据和流信息)中处理元数据。
  The last chapter, Events: Seeking, Navigation and More, will discuss the concept of events in GStreamer. Events are another way of doing application-element interaction. They take care of seeking, for example. They are also yet another way in which elements interact with each other, such as letting each other know about media stream discontinuities, forwarding tags inside a pipeline and so on.
  最后一章Events，阐述Event的概念，包括Seeking、Navigation等。Events是应用-元素交互的另一种方式，比如负责Seeking查询。它们也是元素彼此之间交互的方式，比如让彼此知道媒体流是不连续的，或者在管道中转发标记等等。
• Creating special element types - Explanation of writing other plugin types.
  创建特殊元素类型——如何编写其它类型的插件
  Because the first two parts of the guide use an audio filter as an example, the concepts introduced apply to filter plugins. But many of the concepts apply equally to other plugin types, including sources, sinks, and autopluggers. 因为指南的前两部分使用了音频过滤器作为示例，介绍的概念适用于过滤器插件。但是这些概念同样适用于其他插件类型，包括输出源sources、输入sinks和自动插件。
  This part of the guide presents the issues that arise when working on these more specialized plugin types. The chapter starts with a special focus on elements that can be written using a base-class (Pre-made base classes), and later also goes into writing special types of elements in Writing a Demuxer or Parser, Writing a N-to-1 Element or Muxer and Writing a Manager.本部分介绍了在处理这些特殊的插件类型时，容易出现的问题。从元素上一个特殊聚焦点开始，先写一个基类的元素，再编写特殊类型的元素：写一个 Demuxer 或者Parser,写一个N-1的元素或Muxer，写一个Manager。
• Appendices - Further information for plugin developers.
  附录——提供给插件开发者的更多信息。
  The appendices contain some information that stubbornly refuses to fit cleanly in other sections of the guide. Most of this section is not yet finished.附录中包含的内容，与指南的其他章节格格不入，所以单独在这部分阐述。这部分的大部分还没有完成。

The remainder of this introductory part of the guide presents a short overview of the basic concepts involved in GStreamer plugin development. Topics covered include Elements and Plugins, Pads, GstMiniObject, Buffers and Events and Media types and Properties. If you are already familiar with this information, you can use this short overview to refresh your memory, or you can skip to Building a Plugin.
本指南的导论部分简要概述了GStreamer插件开发中涉及的基本概念。主题包括元素Elements 和插件Plugins，衬垫Pads, GstMiniObject，缓冲区Buffers，Events ，媒体类型Media types和属性Properties。如果你已经对这些概念比较熟悉了，你可以简短的复习一下，或者跳过这部分直接开始开发插件。
As you can see, there’s a lot to learn, so let’s get started!
你看，学的东西还蛮多，我们开始吧！

• Creating compound and complex elements by extending from a GstBin. This will allow you to create plugins that have other plugins embedded in them.
  通过从GstBin扩展创建复合和复杂元素，这也可以创建包含了其他插件的大插件。
• Adding new media types to the registry along with typedetect functions. This will allow your plugin to operate on a completely new media type.通过侦测函数把新的媒体类型添加到注册表。这可以让插件在一个全新的媒体类型上进行工作运作。