manual-intro-basics.md

   1 ---
   2 title: Foundations
   3 ...
   4
   5 # Foundations
   6
   7 This chapter of the guide introduces the basic concepts of GStreamer.
   8 Understanding these concepts will be important in reading any of the
   9 rest of this guide, all of them assume understanding of these basic
  10 concepts.
  11
  12 ## Elements
  13
  14 An *element* is the most important class of objects in GStreamer. You
  15 will usually create a chain of elements linked together and let data
  16 flow through this chain of elements. An element has one specific
  17 function, which can be the reading of data from a file, decoding of this
  18 data or outputting this data to your sound card (or anything else). By
  19 chaining together several such elements, you create a *pipeline* that
  20 can do a specific task, for example media playback or capture. GStreamer
  21 ships with a large collection of elements by default, making the
  22 development of a large variety of media applications possible. If
  23 needed, you can also write new elements. That topic is explained in
  24 great deal in the *GStreamer Plugin Writer's Guide*.
  25
  26 ## Pads
  27
  28 *Pads* are element's input and output, where you can connect other
  29 elements. They are used to negotiate links and data flow between
  30 elements in GStreamer. A pad can be viewed as a “plug” or “port” on an
  31 element where links may be made with other elements, and through which
  32 data can flow to or from those elements. Pads have specific data
  33 handling capabilities: a pad can restrict the type of data that flows
  34 through it. Links are only allowed between two pads when the allowed
  35 data types of the two pads are compatible. Data types are negotiated
  36 between pads using a process called *caps negotiation*. Data types are
  37 described as a `GstCaps`.
  38
  39 An analogy may be helpful here. A pad is similar to a plug or jack on a
  40 physical device. Consider, for example, a home theater system consisting
  41 of an amplifier, a DVD player, and a (silent) video projector. Linking
  42 the DVD player to the amplifier is allowed because both devices have
  43 audio jacks, and linking the projector to the DVD player is allowed
  44 because both devices have compatible video jacks. Links between the
  45 projector and the amplifier may not be made because the projector and
  46 amplifier have different types of jacks. Pads in GStreamer serve the
  47 same purpose as the jacks in the home theater system.
  48
  49 For the most part, all data in GStreamer flows one way through a link
  50 between elements. Data flows out of one element through one or more
  51 *source pads*, and elements accept incoming data through one or more
  52 *sink pads*. Source and sink elements have only source and sink pads,
  53 respectively. Data usually means buffers (described by the
  54 [`GstBuffer`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/gstreamer-GstBuffer.html)
  55 object) and events (described by the
  56 [`GstEvent`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/gstreamer-GstEvent.html)
  57 object).
  58
  59 ## Bins and pipelines
  60
  61 A *bin* is a container for a collection of elements. Since bins are
  62 subclasses of elements themselves, you can mostly control a bin as if it
  63 were an element, thereby abstracting away a lot of complexity for your
  64 application. You can, for example change state on all elements in a bin
  65 by changing the state of that bin itself. Bins also forward bus messages
  66 from their contained children (such as error messages, tag messages or
  67 EOS messages).
  68
  69 A *pipeline* is a top-level bin. It provides a bus for the application
  70 and manages the synchronization for its children. As you set it to
  71 PAUSED or PLAYING state, data flow will start and media processing will
  72 take place. Once started, pipelines will run in a separate thread until
  73 you stop them or the end of the data stream is reached.
  74
  75 ![GStreamer pipeline for a simple ogg player](images/simple-player.png
  76 "fig:")
  77
  78 ## Communication
  79
  80 GStreamer provides several mechanisms for communication and data
  81 exchange between the *application* and the *pipeline*.
  82
  83   - *buffers* are objects for passing streaming data between elements in
  84     the pipeline. Buffers always travel from sources to sinks
  85     (downstream).
  86
  87   - *events* are objects sent between elements or from the application
  88     to elements. Events can travel upstream and downstream. Downstream
  89     events can be synchronised to the data flow.
  90
  91   - *messages* are objects posted by elements on the pipeline's message
  92     bus, where they will be held for collection by the application.
  93     Messages can be intercepted synchronously from the streaming thread
  94     context of the element posting the message, but are usually handled
  95     asynchronously by the application from the application's main
  96     thread. Messages are used to transmit information such as errors,
  97     tags, state changes, buffering state, redirects etc. from elements
  98     to the application in a thread-safe way.
  99
 100   - *queries* allow applications to request information such as duration
 101     or current playback position from the pipeline. Queries are always
 102     answered synchronously. Elements can also use queries to request
 103     information from their peer elements (such as the file size or
 104     duration). They can be used both ways within a pipeline, but
 105     upstream queries are more common.
 106
 107 ![GStreamer pipeline with different communication
 108 flows](images/communication.png "fig:")
 109