7 A bin is a container element. You can add elements to a bin. Since a bin
8 is an element itself, a bin can be handled in the same way as any other
9 element. Therefore, the whole previous chapter
10 ([Elements](manual-elements.md)) applies to bins as well.
14 Bins allow you to combine a group of linked elements into one logical
15 element. You do not deal with the individual elements anymore but with
16 just one element, the bin. We will see that this is extremely powerful
17 when you are going to construct complex pipelines since it allows you to
18 break up the pipeline in smaller chunks.
20 The bin will also manage the elements contained in it. It will perform
21 state changes on the elements as well as collect and forward bus
24 ![Visualisation of a bin with some elements in
25 it](images/bin-element.png "fig:")
27 There is one specialized type of bin available to the GStreamer
30 - A pipeline: a generic container that manages the synchronization and
31 bus messages of the contained elements. The toplevel bin has to be a
32 pipeline, every application thus needs at least one of these.
36 Bins are created in the same way that other elements are created, i.e.
37 using an element factory. There are also convenience functions available
38 (`gst_bin_new ()` and `gst_pipeline_new ()`). To add elements to a bin
39 or remove elements from a bin, you can use `gst_bin_add ()` and
40 `gst_bin_remove ()`. Note that the bin that you add an element to will
41 take ownership of that element. If you destroy the bin, the element will
42 be dereferenced with it. If you remove an element from a bin, it will be
43 dereferenced automatically.
52 GstElement *bin, *pipeline, *source, *sink;
55 gst_init (&argc, &argv);
58 pipeline = gst_pipeline_new ("my_pipeline");
59 bin = gst_bin_new ("my_bin");
60 source = gst_element_factory_make ("fakesrc", "source");
61 sink = gst_element_factory_make ("fakesink", "sink");
63 /* First add the elements to the bin */
64 gst_bin_add_many (GST_BIN (bin), source, sink, NULL);
65 /* add the bin to the pipeline */
66 gst_bin_add (GST_BIN (pipeline), bin);
68 /* link the elements */
69 gst_element_link (source, sink);
77 There are various functions to lookup elements in a bin. The most
78 commonly used are `gst_bin_get_by_name ()` and `gst_bin_get_by_interface
79 ()`. You can also iterate over all elements that a bin contains using
80 the function `gst_bin_iterate_elements ()`. See the API references of
81 [`GstBin`](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstBin.html)
86 The application programmer can create custom bins packed with elements
87 to perform a specific task. This allows you, for example, to write an
88 Ogg/Vorbis decoder with just the following lines of code:
98 gst_init (&argc, &argv);
101 player = gst_element_factory_make ("oggvorbisplayer", "player");
103 /* set the source audio file */
104 g_object_set (player, "location", "helloworld.ogg", NULL);
107 gst_element_set_state (GST_ELEMENT (player), GST_STATE_PLAYING);
113 (This is a silly example of course, there already exists a much more
114 powerful and versatile custom bin like this: the playbin element.)
116 Custom bins can be created with a plugin or from the application. You
117 will find more information about creating custom bin in the [Plugin
119 Guide](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html).
121 Examples of such custom bins are the playbin and uridecodebin elements
122 from[gst-plugins-base](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html).
124 ## Bins manage states of their children
126 Bins manage the state of all elements contained in them. If you set a
127 bin (or a pipeline, which is a special top-level type of bin) to a
128 certain target state using `gst_element_set_state ()`, it will make sure
129 all elements contained within it will also be set to this state. This
130 means it's usually only necessary to set the state of the top-level
131 pipeline to start up the pipeline or shut it down.
133 The bin will perform the state changes on all its children from the sink
134 element to the source element. This ensures that the downstream element
135 is ready to receive data when the upstream element is brought to PAUSED
136 or PLAYING. Similarly when shutting down, the sink elements will be set
137 to READY or NULL first, which will cause the upstream elements to
138 receive a FLUSHING error and stop the streaming threads before the
139 elements are set to the READY or NULL state.
141 Note, however, that if elements are added to a bin or pipeline that's
142 already running, , e.g. from within a "pad-added" signal callback, its
143 state will not automatically be brought in line with the current state
144 or target state of the bin or pipeline it was added to. Instead, you
145 have to need to set it to the desired target state yourself using
146 `gst_element_set_state ()` or `gst_element_sync_state_with_parent ()`
147 when adding elements to an already-running pipeline.