* specified manual buffer metrics it is recommended to update
* them with pa_stream_set_buffer_attr() to compensate for the
* changed frame sizes. Only supported when the server is at least
- * PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
+ * PA 0.9.8. It is ignored on older servers.
+ *
+ * When creating streams with pa_stream_new_extended(), this flag has no
+ * effect. If you specify a format with PCM encoding, and you want the
+ * server to choose the sample format, then you should leave the sample
+ * format unspecified in the pa_format_info object. This also means that
+ * you can't use pa_format_info_from_sample_spec(), because that function
+ * always sets the sample format.
+ *
+ * \since 0.9.8 */
PA_STREAM_FIX_RATE = 0x0080U,
/**< Use the sample rate of the sink, and possibly ignore the rate
* the sample spec contains. Usage similar to
- * PA_STREAM_FIX_FORMAT.Only supported when the server is at least
- * PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
+ * PA_STREAM_FIX_FORMAT. Only supported when the server is at least
+ * PA 0.9.8. It is ignored on older servers.
+ *
+ * When creating streams with pa_stream_new_extended(), this flag has no
+ * effect. If you specify a format with PCM encoding, and you want the
+ * server to choose the sample rate, then you should leave the rate
+ * unspecified in the pa_format_info object. This also means that you can't
+ * use pa_format_info_from_sample_spec(), because that function always sets
+ * the sample rate.
+ *
+ * \since 0.9.8 */
PA_STREAM_FIX_CHANNELS = 0x0100,
/**< Use the number of channels and the channel map of the sink,
* and possibly ignore the number of channels and the map the
* sample spec and the passed channel map contains. Usage similar
* to PA_STREAM_FIX_FORMAT. Only supported when the server is at
- * least PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
+ * least PA 0.9.8. It is ignored on older servers.
+ *
+ * When creating streams with pa_stream_new_extended(), this flag has no
+ * effect. If you specify a format with PCM encoding, and you want the
+ * server to choose the channel count and/or channel map, then you should
+ * leave the channels and/or the channel map unspecified in the
+ * pa_format_info object. This also means that you can't use
+ * pa_format_info_from_sample_spec(), because that function always sets
+ * the channel count (but if you only want to leave the channel map
+ * unspecified, then pa_format_info_from_sample_spec() works, because it
+ * accepts a NULL channel map).
+ *
+ * \since 0.9.8 */
PA_STREAM_DONT_MOVE = 0x0200U,
/**< Don't allow moving of this stream to another