PipeWire: SPA POD

PipeWire 0.3.51

SPA POD

POD (plain old data) is a sort of data container.

It is comparable to DBus Variant or LV2 Atom.

A POD can express nested structures of Objects (with properties), Vectors, Arrays, sequences and various primitives types. All information in the POD is laid out sequentially in memory and can be written directly to storage or exchanged between processes or threads without additional marshalling.

Each POD is made of a 32 bits size followed by a 32 bits type field, followed by the pod contents. This makes it possible to skip over unknown POD types. The POD start is always aligned to 8 bytes.

PODs can be efficiently constructed and parsed in real-time threads without requiring memory allocations.

PODs use the SPA type system for the basic types and containers. See the SPA types for more info.

## Types

PODs can contain a number of basic SPA types:

- `SPA_TYPE_None`: no value or a NULL pointer.
- `SPA_TYPE_Bool`: a boolean value
- `SPA_TYPE_Id`: an enumerated value
- `SPA_TYPE_Int`, `SPA_TYPE_Long`, `SPA_TYPE_Float`, `SPA_TYPE_Double`:
- various numeral types, 32 and 64 bits.
- `SPA_TYPE_String`: a string
- `SPA_TYPE_Bytes`: a byte array
- `SPA_TYPE_Rectangle`: a rectangle with width and height
- `SPA_TYPE_Fraction`: a fraction with numerator and denominator
- `SPA_TYPE_Bitmap`: an array of bits

PODs can be grouped together in these container types:

- `SPA_TYPE_Array`: an array of equal sized objects
- `SPA_TYPE_Struct`: a collection of types and objects
- `SPA_TYPE_Object`: an object with properties
- `SPA_TYPE_Sequence`: a timed sequence of PODs

PODs can also contain some extra types:

- `SPA_TYPE_Pointer`: a typed pointer in memory
- `SPA_TYPE_Fd`: a file descriptor
- `SPA_TYPE_Choice`: a choice of values
- `SPA_TYPE_Pod`: a generic type for the POD itself

# Constructing a POD

A POD is usually constructed with a `struct spa_pod_builder`. The builder needs to be initialized with a memory region to write into. It is also possible to dynamically grow the memory as needed.

The most common way to construct a POD is on the stack. This does not require any memory allocations. The size of the POD can be estimated pretty easily and if the buffer is not large enough, an appropriate error will be generated.

The code fragment below initializes a pod builder to write into the stack allocated buffer.

uint8_t buffer[4096];
struct spa_pod_builder b;
spa_pod_builder_init(&b, buffer, sizeof(buffer));
spa_pod_builder_init
static void spa_pod_builder_init(struct spa_pod_builder *builder, void *data, uint32_t size)
Definition: builder.h:107
spa_pod_builder
Definition: builder.h:73

Next we need to write some object into the builder. Let's write a simple struct with an Int and Float in it. Structs are comparable to JSON arrays.

struct spa_pod_frame f;
spa_pod_builder_push_struct(&b, &f);
spa_pod_builder_push_struct
static int spa_pod_builder_push_struct(struct spa_pod_builder *builder, struct spa_pod_frame *frame)
Definition: builder.h:440
spa_pod_frame
Definition: iter.h:47

First we open the struct container, the `struct spa_pod_frame` keeps track of the container context. Next we add some values to the container like this:

spa_pod_builder_int(&b, 5);
spa_pod_builder_float(&b, 3.1415f);
spa_pod_builder_float
static int spa_pod_builder_float(struct spa_pod_builder *builder, float val)
Definition: builder.h:283
spa_pod_builder_int
static int spa_pod_builder_int(struct spa_pod_builder *builder, int32_t val)
Definition: builder.h:265

Then we close the container by popping the frame again:

struct spa_pod *pod;
pod = spa_pod_builder_pop(&b, &f);
spa_pod_builder_pop
static void * spa_pod_builder_pop(struct spa_pod_builder *builder, struct spa_pod_frame *frame)
Definition: builder.h:186
spa_pod
Definition: pod.h:63

`spa_pod_builder_pop()` returns a reference to the object we completed on the stack.

## Using varargs builder.

We can also use the following construct to make POD objects:

spa_pod_builder_push_struct(&b, &f);
spa_pod_builder_add(&b,
SPA_POD_Int(5),
SPA_POD_Float(3.1415f));
pod = spa_pod_builder_pop(&b, &f);
spa_pod_builder_add
static int spa_pod_builder_add(struct spa_pod_builder *builder,...)
Definition: builder.h:665
SPA_POD_Float
#define SPA_POD_Float(val)
Definition: vararg.h:96
SPA_POD_Int
#define SPA_POD_Int(val)
Definition: vararg.h:74

Or even shorter:

pod = spa_pod_builder_add_struct(&b,
SPA_POD_Int(5),
SPA_POD_Float(3.1415f));
spa_pod_builder_add_struct
#define spa_pod_builder_add_struct(b,...)
Definition: builder.h:685

It's not possible to use the varargs builder to make a Sequence or Array, use the normal builder methods for that.

## Making objects

POD objects are containers for properties and are comparable to JSON objects.

Start by pushing an object:

spa_pod_builder_push_object(&b, &f, SPA_TYPE_OBJECT_Props, SPA_PARAM_Props);
SPA_PARAM_Props
@ SPA_PARAM_Props
properties as SPA_TYPE_OBJECT_Props
Definition: param.h:52
spa_pod_builder_push_object
static int spa_pod_builder_push_object(struct spa_pod_builder *builder, struct spa_pod_frame *frame, uint32_t type, uint32_t id)
Definition: builder.h:453
SPA_TYPE_OBJECT_Props
@ SPA_TYPE_OBJECT_Props
Definition: type.h:95

An object requires an object type (`SPA_TYPE_OBJECT_Props`) and a context id (`SPA_PARAM_Props`). The object type defines the properties that can be added to the object and their meaning. The SPA type system allows you to make this connection (See the type system).

Next we can push some properties in the object:

spa_pod_builder_prop(&b, SPA_PROP_device, 0);
spa_pod_builder_string(&b, "hw:0");
spa_pod_builder_prop(&b, SPA_PROP_frequency, 0);
spa_pod_builder_float(&b, 440.0);
SPA_PROP_device
@ SPA_PROP_device
Definition: props.h:67
SPA_PROP_frequency
@ SPA_PROP_frequency
Definition: props.h:85
spa_pod_builder_prop
static int spa_pod_builder_prop(struct spa_pod_builder *builder, uint32_t key, uint32_t flags)
Definition: builder.h:468
spa_pod_builder_string
static int spa_pod_builder_string(struct spa_pod_builder *builder, const char *str)
Definition: builder.h:323

As can be seen, we always need to push a prop (with key and flags) and then the associated value. For performance reasons it is a good idea to always push (and parse) the object keys in ascending order.

Don't forget to pop the result when the object is finished:

pod = spa_pod_builder_pop(&b, &f);

There is a shortcut for making objects:

pod = spa_pod_builder_add_object(&b,
SPA_TYPE_OBJECT_Props, SPA_PARAM_Props,
SPA_PROP_device, SPA_POD_String("hw:0"),
SPA_PROP_frequency, SPA_POD_Float(440.0f));
SPA_POD_String
#define SPA_POD_String(val)
Definition: vararg.h:114
spa_pod_builder_add_object
#define spa_pod_builder_add_object(b, type, id,...)
Definition: builder.h:677

## Choice values

It is possible to express ranges or enumerations of possible values for properties (and to some extend structs). This is achieved with Choice values.

Choice values are really just a choice type and an array of choice values (of the same type). Depending on the choice type, the array values are interpreted in different ways:

`SPA_CHOICE_None`: no choice, first value is current `SPA_CHOICE_Range`: range: default, min, max `SPA_CHOICE_Step`: range with step: default, min, max, step `SPA_CHOICE_Enum`: enum: default, alternative,... `SPA_CHOICE_Flags`: bitmask of flags

Let's illustrate this with a Props object that specifies a range of possible values for the frequency:

struct spa_pod_frame f2;
spa_pod_builder_push_object(&b, &f, SPA_TYPE_OBJECT_Props, SPA_PARAM_Props);
spa_pod_builder_prop(&b, SPA_PROP_frequency, 0);
spa_pod_builder_push_choice(&b, &f2, SPA_CHOICE_Range, 0);
spa_pod_builder_float(&b, 440.0); // default
spa_pod_builder_float(&b, 110.0); // min
spa_pod_builder_float(&b, 880.0); // min
pod = spa_pod_builder_pop(&b, &f2);
pod = spa_pod_builder_pop(&b, &f);
spa_pod_builder_push_choice
static int spa_pod_builder_push_choice(struct spa_pod_builder *builder, struct spa_pod_frame *frame, uint32_t type, uint32_t flags)
Definition: builder.h:424
SPA_CHOICE_Range
@ SPA_CHOICE_Range
range: default, min, max
Definition: pod.h:168
spa_pod_frame::pod
struct spa_pod pod
Definition: iter.h:48

As you can see, first push the choice as a Range, then the values. A Range choice expects at least 3 values, the default value, minimum and maximum values. There is a shortcut for this as well using varargs:

pod = spa_pod_builder_add_object(&b,
SPA_TYPE_OBJECT_Props, SPA_PARAM_Props,
SPA_PROP_frequency, SPA_POD_CHOICE_RANGE_Float(440.0f, 110.0f, 880.0f));
SPA_POD_CHOICE_RANGE_Float
#define SPA_POD_CHOICE_RANGE_Float(def, min, max)
Definition: vararg.h:100

## Choice examples

This is a description of a possible `SPA_TYPE_OBJECT_Format` as used when enumerating allowed formats (`SPA_PARAM_EnumFormat`) in SPA objects:

pod = spa_pod_builder_add_object(&b,
SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
// specify the media type and subtype
SPA_FORMAT_mediaType, SPA_POD_Id(SPA_MEDIA_TYPE_audio),
SPA_FORMAT_mediaSubtype, SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
// audio/raw properties
SPA_FORMAT_AUDIO_format, SPA_POD_CHOICE_ENUM_Id(
SPA_AUDIO_FORMAT_S16, // default
SPA_AUDIO_FORMAT_S16, // alternative1
SPA_AUDIO_FORMAT_S32, // alternative2
SPA_AUDIO_FORMAT_f32 // alternative3
),
SPA_FORMAT_AUDIO_rate, SPA_POD_CHOICE_RANGE_Int(
44100, // default
8000, // min
192000 // max
),
SPA_FORMAT_AUDIO_channels, SPA_POD_Int(2));
SPA_MEDIA_TYPE_audio
@ SPA_MEDIA_TYPE_audio
Definition: format.h:47
SPA_PARAM_EnumFormat
@ SPA_PARAM_EnumFormat
available formats as SPA_TYPE_OBJECT_Format
Definition: param.h:53
SPA_FORMAT_mediaType
@ SPA_FORMAT_mediaType
media type (Id enum spa_media_type)
Definition: format.h:109
SPA_FORMAT_AUDIO_rate
@ SPA_FORMAT_AUDIO_rate
sample rate (Int)
Definition: format.h:116
SPA_FORMAT_mediaSubtype
@ SPA_FORMAT_mediaSubtype
media subtype (Id enum spa_media_subtype)
Definition: format.h:110
SPA_FORMAT_AUDIO_format
@ SPA_FORMAT_AUDIO_format
audio format, (Id enum spa_audio_format)
Definition: format.h:114
SPA_FORMAT_AUDIO_channels
@ SPA_FORMAT_AUDIO_channels
number of audio channels (Int)
Definition: format.h:117
SPA_MEDIA_SUBTYPE_raw
@ SPA_MEDIA_SUBTYPE_raw
Definition: format.h:58
SPA_AUDIO_FORMAT_S32
@ SPA_AUDIO_FORMAT_S32
Definition: raw.h:118
SPA_AUDIO_FORMAT_S16
@ SPA_AUDIO_FORMAT_S16
Definition: raw.h:114
SPA_POD_CHOICE_ENUM_Id
#define SPA_POD_CHOICE_ENUM_Id(n_vals,...)
Definition: vararg.h:71
SPA_POD_CHOICE_RANGE_Int
#define SPA_POD_CHOICE_RANGE_Int(def, min, max)
Definition: vararg.h:78
SPA_POD_Id
#define SPA_POD_Id(val)
Definition: vararg.h:69
SPA_TYPE_OBJECT_Format
@ SPA_TYPE_OBJECT_Format
Definition: type.h:96

## Fixate

We can remove all choice values from the object with the `spa_pod_object_fixate()` method. This modifies the pod in-place and sets all choice properties to `SPA_CHOICE_None`, forcing the default value as the only available value in the choice.

Running fixate on our previous example would result in an object equivalent to:

pod = spa_pod_builder_add_object(&b,
SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
// specify the media type and subtype
SPA_FORMAT_mediaType, SPA_POD_Id(SPA_MEDIA_TYPE_audio),
SPA_FORMAT_mediaSubtype, SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
// audio/raw properties
SPA_FORMAT_AUDIO_format, SPA_POD_Id(SPA_AUDIO_FORMAT_S16),
SPA_FORMAT_AUDIO_rate, SPA_POD_Int(44100),
SPA_FORMAT_AUDIO_channels, SPA_POD_Int(2));

# Parsing a POD

Parsing a POD usually consists of

validating if raw bytes + size can contain a valid pod inspecting the type of a pod looping over the items in an object or struct getting data out of PODs.

## Validating bytes

Use `spa_pod_from_data()` to check if maxsize of bytes in data contain a POD at the size bytes starting at offset. This function checks that the POD size will fit and not overflow.

struct spa_pod *pod;
pod = spa_pod_from_data(data, maxsize, offset, size);
spa_pod_from_data
static void * spa_pod_from_data(void *data, size_t maxsize, off_t offset, size_t size)
Definition: iter.h:140
spa_pod::size
uint32_t size
Definition: pod.h:64

## Checking the type of POD

Use one of `spa_pod_is_bool()`, `spa_pod_is_int()`, etc to check for the type of the pod. For simple (non-container) types, `spa_pod_get_bool()`, `spa_pod_get_int()` etc can be used to extract the value of the pod.

`spa_pod_is_object_type()` can be used to check if the POD contains an object of the expected type.

## Struct fields

To iterate over the fields of a Struct use:

struct spa_pod *pod, *obj;
SPA_POD_STRUCT_FOREACH(obj, pod) {
printf("field type:%d\n", pod->type);
}
SPA_POD_STRUCT_FOREACH
#define SPA_POD_STRUCT_FOREACH(obj, iter)
Definition: iter.h:120
spa_pod::type
uint32_t type
Definition: pod.h:65

For parsing Structs it is usually much easier to use the parser below.

## Object Properties

To iterate over the properties in an object you can do:

struct spa_pod_prop *prop;
struct spa_pod_object *obj = (struct spa_pod_object*)pod;
SPA_POD_OBJECT_FOREACH(pod, prop) {
printf("prop key:%d\n", prop->key);
}
SPA_POD_OBJECT_FOREACH
#define SPA_POD_OBJECT_FOREACH(obj, iter)
Definition: iter.h:128
spa_pod_object
Definition: pod.h:203
spa_pod_object::pod
struct spa_pod pod
Definition: pod.h:204
spa_pod_prop
Definition: pod.h:228
spa_pod_prop::key
uint32_t key
key of property, list of valid keys depends on the object type
Definition: pod.h:229

There is a function to retrieve the property for a certain key in the object. If the properties of the object are in ascending order, you can start searching from the previous key.

struct spa_pod_prop *prop;
prop = spa_pod_find_prop(obj, NULL, SPA_FORMAT_AUDIO_format);
// .. use first prop
prop = spa_pod_find_prop(obj, prop, SPA_FORMAT_AUDIO_rate);
// .. use next prop
spa_pod_find_prop
static const struct spa_pod_prop * spa_pod_find_prop(const struct spa_pod *pod, const struct spa_pod_prop *start, uint32_t key)
Definition: iter.h:428

## Parser

Similar to the builder, there is a parser object as well.

If the fields in a struct are known, it is much easier to use the parser. Similarly, if the object type (and thus its keys) are known, the parser is easier.

First initialize a `struct spa_pod_parser`:

struct spa_pod_parser p;
spa_pod_parser_pod(&p, obj);
spa_pod_parser_pod
static void spa_pod_parser_pod(struct spa_pod_parser *parser, const struct spa_pod *pod)
Definition: parser.h:70
spa_pod_parser
Definition: parser.h:54

You can then enter containers such as objects or structs with a push operation:

struct spa_pod_frame f;
spa_pod_parser_push_struct(&p, &f);
spa_pod_parser_push_struct
static int spa_pod_parser_push_struct(struct spa_pod_parser *parser, struct spa_pod_frame *frame)
Definition: parser.h:259

You need to store the context in a `struct spa_pod_frame` to be able to exit the container again later.

You can then parse each field. The parser takes care of moving to the next field.

uint32_t id, val;
spa_pod_parser_get_id(&p, &id);
spa_pod_parser_get_int(&p, &val);
...
spa_pod_parser_get_int
static int spa_pod_parser_get_int(struct spa_pod_parser *parser, int32_t *value)
Definition: parser.h:160
spa_pod_parser_get_id
static int spa_pod_parser_get_id(struct spa_pod_parser *parser, uint32_t *value)
Definition: parser.h:151

And finally exit the container again:

spa_pod_parser_pop(&p, &f);
spa_pod_parser_pop
static int spa_pod_parser_pop(struct spa_pod_parser *parser, struct spa_pod_frame *frame)
Definition: parser.h:134

## Parser with variable arguments

In most cases, parsing objects is easier with the variable argument functions. The parse function look like the mirror image of the builder functions.

To parse a struct:

spa_pod_parser_get_struct(&p,
SPA_POD_Id(&id),
SPA_POD_Int(&val));
spa_pod_parser_get_struct
#define spa_pod_parser_get_struct(p,...)
Definition: parser.h:574

To parse properties in an object:

uint32_t type, subtype, format, rate, channels;
spa_pod_parser_get_object(&p,
SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
SPA_FORMAT_mediaType, SPA_POD_Id(&type),
SPA_FORMAT_mediaSubtype, SPA_POD_Id(&subtype),
SPA_FORMAT_AUDIO_format, SPA_POD_Id(&format),
SPA_FORMAT_AUDIO_rate, SPA_POD_Int(&rate),
SPA_FORMAT_AUDIO_channels, SPA_POD_Int(&channels));
spa_pod_parser_get_object
#define spa_pod_parser_get_object(p, type, id,...)
Definition: parser.h:563

When parsing objects it is possible to have optional fields. You can make a field optional be parsing it with the `SPA_POD_OPT_` prefix for the type.

In the next example, the rate and channels fields are optional and when they are not present, the variables will not be changed.

uint32_t type, subtype, format, rate = 0, channels = 0;
spa_pod_parser_get_object(&p,
SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
SPA_FORMAT_mediaType, SPA_POD_Id(&type),
SPA_FORMAT_mediaSubtype, SPA_POD_Id(&subtype),
SPA_FORMAT_AUDIO_format, SPA_POD_Id(&format),
SPA_FORMAT_AUDIO_rate, SPA_POD_OPT_Int(&rate),
SPA_FORMAT_AUDIO_channels, SPA_POD_OPT_Int(&channels));
SPA_POD_OPT_Int
#define SPA_POD_OPT_Int(val)
Definition: parser.h:531

It is not possible to parse a Sequence or Array with the parser. Use the iterator for this.

## Choice values

The parser will handle Choice values as long as they are of type None. It will then parse the single value from the choice. When dealing with other choice values, it's possible to parse the property values into a `struct spa_pod` and then inspect the Choice manually, if needed.

Here is an example of parsing the format values as a POD:

uint32_t type, subtype;
struct spa_pod *format;
spa_pod_parser_get_object(&p,
SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
SPA_FORMAT_mediaType, SPA_POD_Id(&type),
SPA_FORMAT_mediaSubtype, SPA_POD_Id(&subtype),
SPA_FORMAT_AUDIO_format, SPA_POD_Pod(&format));
SPA_POD_Pod
#define SPA_POD_Pod(val)
Definition: vararg.h:148

`spa_pod_get_values()` is a useful function. It returns a `struct spa_pod*` with and array of values. For normal PODs and Choice None values, it simply returns the POD and 1 value. For other Choice values it returns the Choice type and an array of values:

struct spa_pod *value;
uint32_t n_vals, choice;
value = spa_pod_get_values(pod, &n_vals, &choice);
switch (choice) {
case SPA_CHOICE_None:
// one single value
break;
case SPA_CHOICE_Range:
// array of values of type of pod, cast to right type
// to iterate.
uint32_t *v = SPA_POD_BODY(values);
if (n_vals < 3)
break;
printf("default value: %u\n", v[0]);
printf("min value: %u\n", v[1]);
printf("max value: %u\n", v[2]);
break;
// ...
default:
break;
}
SPA_POD_BODY
#define SPA_POD_BODY(pod)
Definition: pod.h:59
spa_pod_get_values
static struct spa_pod * spa_pod_get_values(const struct spa_pod *pod, uint32_t *n_vals, uint32_t *choice)
Definition: iter.h:367
SPA_CHOICE_None
@ SPA_CHOICE_None
no choice, first value is current
Definition: pod.h:167

# Filter

Given 2 pod objects of the same type (Object, Struct, ..) one can run a filter and generate a new pod that only contains values that are compatible with both input pods.

This is, for example, used to find a compatible format between two ports.

As an example we can run a filter on two simple PODs:

pod = spa_pod_builder_add_object(&b,
SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
SPA_FORMAT_mediaType, SPA_POD_Id(SPA_MEDIA_TYPE_audio),
SPA_FORMAT_mediaSubtype, SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
SPA_FORMAT_AUDIO_format, SPA_POD_CHOICE_ENUM_Id(
SPA_AUDIO_FORMAT_S16, // default
SPA_AUDIO_FORMAT_S16, // alternative1
SPA_AUDIO_FORMAT_S32, // alternative2
SPA_AUDIO_FORMAT_f32 // alternative3
));
filter = spa_pod_builder_add_object(&b,
SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
SPA_FORMAT_mediaType, SPA_POD_Id(SPA_MEDIA_TYPE_audio),
SPA_FORMAT_mediaSubtype, SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
SPA_FORMAT_AUDIO_format, SPA_POD_CHOICE_ENUM_Id(
SPA_AUDIO_FORMAT_S16, // default
SPA_AUDIO_FORMAT_S16, // alternative1
SPA_AUDIO_FORMAT_f64 // alternative2
));
struct spa_pod *result;
if (spa_pod_filter(&b, &result, pod, filter) < 0)
goto exit_error;
spa_pod_filter
static int spa_pod_filter(struct spa_pod_builder *b, struct spa_pod **result, const struct spa_pod *pod, const struct spa_pod *filter)
Definition: filter.h:392

Filter will contain a POD equivalent to:

result = spa_pod_builder_add_object(&b,
SPA_TYPE_OBJECT_Format, SPA_PARAM_EnumFormat,
SPA_FORMAT_mediaType, SPA_POD_Id(SPA_MEDIA_TYPE_audio),
SPA_FORMAT_mediaSubtype, SPA_POD_Id(SPA_MEDIA_SUBTYPE_raw),
SPA_FORMAT_AUDIO_format, SPA_AUDIO_FORMAT_S16);

# POD layout

Each POD has a 32 bits size field, followed by a 32 bits type field. The size field specifies the size following the type field.

Each POD is aligned to an 8 byte boundary.