6 Reference
Upipe defines common standard attributes for struct uref and common standard flow definition tokens.
6.1 Attributes reference
Attributes may stored in three manners:
Directly in the uref structure: It is the case for very frequently accessed attributes where performance is critical, such as pts, dts or systime.
In the udict, as a shorthand: A code has been allocated to the attribute, which allows it to be retrieved without any string comparison (sometimes accessed).
In the udict, as a normal key/value pair: String comparisons are used to find the appropriate attribute (adequate for rarely accessed attributes).
However Upipe exposes the same API for all three types. The difference lies in the declaration of the attribute in the corresponding header file, where different macros are used for each case, for instance for an unsigned attribute named foo, in the category bar:
UREF_ATTR_UNSIGNED_UREF(bar, foo, foo, attribute storing the value of foo)
UREF_ATTR_UNSIGNED_SH(bar, foo, UDICT_TYPE_BAR_FOO, attribute storing the value of foo)
UREF_ATTR_UNSIGNED(bar, foo, "bar.foo", attribute storing the value of foo)
In the third case, an attribute name in the udict structure must be determined, so that it doesn't conflict with an already existing attribute. By convention, a short name of the attribute is prefixed by a letter indicating its category, and a dot. Attributes which are only used internally may be prefixed by "x.", which is reserved for this purpose.
Any of these macros declares the following inline functions:
bool uref_bar_get_foo(struct uref *, uint64_t *)
bool uref_bar_set_foo(struct uref *, uint64_t)
bool uref_bar_delete_foo(struct uref *)
bool uref_bar_match_foo(struct uref *, uint64_t min, uint64_t max)
By conventions, attributes are classified in a category. The following paragraphs list the existing attributes, by category.
Clock
| name | type | description |
|---|---|---|
| rap_sys | unsigned | reception time in system clock of the last random access point, allowing to decode the current uref |
| date_prog | uref_date | timestamp in program clock |
| date_orig | uref_date | timestamp in stream clock |
| date_sys | uref_date | timestamp in system clock |
| dts_pts_delay | unsigned | delay before the decoding of an access unit, and its presentation timestamp (in 27 MHz units) |
| cr_dts_delay | unsigned | delay before the reception or emission of an access unit, and its decoding timestamp (in 27 MHz units) |
| duration | unsigned | duration of the presentation of an access unit |
| index_rap | small_unsigned | offset in number of access units since the last random access point |
| rate | rational | playing rate (1 being normal play, < 1 slow motion, > 1 fast forward) |
| ref | boolean | flag indicating that the packet carries a clock reference |
Flow
| name | type | description |
|---|---|---|
| end | void | flag only used internally in some core modules to indicate that the source was disconnected |
| discontinuity | void | flag indicating a discontinuity in the data flow occurring just before this uref |
| random | void | flag indicating that this uref is a random access point |
| error | void | flag indicating that this uref carries an unrecoverable error |
| def | string | definition of the flow (see next chapter) |
| raw_def | string | real definition of the flow, used internally by some modules |
| id | unsigned | ID of the flow (unique for a given split pipe) |
| lang | string | ISO-639 language |
| lowdelay | void | flag indicating that the flow definition can be decoded with low latency |
| copyright | void | flag indicating that the content is copyrighted |
| original | void | flag indicating whether the content is a original work or a copy |
| headers | opaque | codec-specific global headers |
Block
| name | type | description |
|---|---|---|
| start | void | flag indicating that the uref starts an access unit |
| header_size | unsigned | size of the (optional) headers that are at the beginning of the ubuf |
Block_flow
| name | type | description |
|---|---|---|
| octetrate | unsigned | flag for CBR flows, number of octets per second |
| max_octetrate | unsigned | maximum number of octets per second admitted by the profile/level of the codec |
| cpb_buffer | unsigned | size of the coded picture buffer in octets |
| prepend | unsigned | number of extra octets added before buffer allocation |
| append | unsigned | number of extra octets added after buffer allocation |
| align | unsigned | alignment of the buffer in octets |
| align_offset | int | offset of the aligned octet in the buffer |
| size | unsigned | for constant-size frames, size of a block |
Pic
| name | type | description |
|---|---|---|
| number | unsigned | picture number from the beginning of the flow |
| hposition | unsigned | horizontal position of a subpicture |
| vposition | unsigned | vertical position of a subpicture |
| progressive | void | flag present for progressive pictures |
| tf | void | top field present |
| bf | void | bottom field present |
| tff | void | top field displayed first |
Pic_flow
| name | type | description |
|---|---|---|
| macropixel | small_unsigned | number of pixels in a macropixel |
| planes | small_unsigned | number of planes |
| hsubsampling | small_unsigned | horizontal subsampling (per plane) |
| vsubsampling | small_unsigned | vertical subsampling (per plane) |
| macropixel_size | small_unsigned | size of a macropixel in octets (per plane) |
| chroma | string | string identifying the chroma (per plane) |
| fps | rational | number of frames per second |
| hmprepend | small_unsigned | extra macropixels added before each line |
| hmappend | small_unsigned | extra macropixels added after each line |
| vprepend | small_unsigned | extra lines added before buffer |
| vappend | small_unsigned | extra lines added after buffer |
| align | unsigned | alignment in octets |
| align_hmoffset | int | horizontal offset of the aligned macropixel |
| sar | rational | sample aspect ratio |
| overscan | void | flag present in case of overscan |
| hsize | unsigned | horizontal size |
| vsize | unsigned | vertical size |
| hsize_visible | unsigned | horizontal visible size |
| vsize_visible | unsigned | vertical visible size |
Sound_flow
| name | type | description |
|---|---|---|
| channels | small_unsigned | number of audio channels |
| sample_size | small_unsigned | size in octets of a sample of an audio channel |
| rate | unsigned | number of samples per second |
| prepend | small_unsigned | extra samples added before each channel |
| align | unsigned | alignment in octets |
| align_offset | int | horizontal offset of the aligned sample |
| samples | unsigned | number of samples per frame |
Program_flow
| name | type | description |
|---|---|---|
| name | string | name of the program |
6.2 Flow definition reference
Flow definitions are strings made up of parts separated by dots, terminated by a dot. The first part of the flow definition points to the type of allocator for the ubuf:
"block.": allocated by a block allocator, responds to ubuf_block_* semantics
"pic.": allocated by a pic allocator, responds to ubuf_pic_* semantics
The other parts describe the content of the flow, from the outermost container to the innermost. For instance, "block.mpegts.mpegtspes.mpeg2video." defines a flow using the block allocator, containing TS packets, containing PES packets, containing an MPEG-2 video elementary stream. An mpeg_ts_decaps module would typically remove the "mpegts." part, and send "block.mpegtspes.mpeg2video." downstream. And so on.
It is very important to keep the last dot, because flow definition matching works with a string comparison, and "block.mpegtspes." should not be matched by a module requiring "block.mpegts.".
Apart from the allocators, the following parts are currently in use:
| part | description |
|---|---|
| mpegts | 188-octet MPEG TS packets (ISO/IEC 13818-1) |
| mpegtspsi | MPEG PSI sections (ISO/IEC 13818-1) |
| mpegtspat | MPEG PSI sections containing PAT (ISO/IEC 13818-1) |
| mpegtspmt | MPEG PSI sections containing PMT (ISO/IEC 13818-1) |
| mpegtspes | MPEG PES packets (ISO/IEC 13818-1) |
| mpeg2video | MPEG-2 video elementary stream (ISO/IEC 13818-2) |
| h264 | MPEG-4 AVC video elementary stream (ISO/IEC 14496-10) |
| pic | indicates that the content is raw video (should also be after a video codec) |
| sound | indicates that the content is raw, packed audio (should also be after an audio codec) |