PROTOCOL

   1 ### v8, implemented by >= 0.8
   2
   3 First version supported.
   4
   5 ### v9, implemented by >= 0.9.0
   6
   7 Reply for PA_COMMAND_CREATE_PLAYBACK_STREAM,
   8 PA_COMMAND_CREATE_RECORD_STREAM now returns buffer_attrs that are used:
   9
  10 Four new fields in reply of PA_COMMAND_CREATE_PLAYBACK_STREAM:
  11
  12    maxlength
  13    tlength
  14    prebuf
  15    minreq
  16
  17 Two new fields in reply of PA_COMMAND_CREATE_RECORD_STREAM:
  18
  19    maxlength
  20    fragsize
  21
  22 ### v10, implemented by >= 0.9.5
  23
  24 New opcodes:
  25
  26  PA_COMMAND_MOVE_SINK_INPUT
  27  PA_COMMAND_MOVE_SOURCE_OUTPUT
  28
  29 SHM data transfer support
  30
  31 ### v11, implemented by >= 0.9.7
  32
  33 Reply to PA_COMMAND_GET_SINK_INPUT_INFO, PA_COMMAND_GET_SINK_INPUT_INFO_LIST gets new field at the end:
  34
  35  mute
  36
  37 New opcodes:
  38
  39  PA_COMMAND_SET_SINK_INPUT_MUTE
  40  PA_COMMAND_SUSPEND_SINK
  41  PA_COMMAND_SUSPEND_SOURCE
  42
  43 ### v12, implemented by >= 0.9.8
  44
  45 S32LE, S32BE is now known as sample spec.
  46
  47 Gained six new bool fields for PA_COMMAND_CREATE_PLAYBACK_STREAM, PA_COMMAND_CREATE_RECORD_STREAM request at the end:
  48
  49  no_remap_channels
  50  no_remix_channels
  51  fix_format
  52  fix_rate
  53  fix_channels
  54  no_move
  55  variable_rate
  56
  57 Reply to these opcodes now includes:
  58
  59  sample_spec
  60  channel_map
  61  device_index
  62  device_name
  63  suspended
  64
  65 New opcodes for changing buffer attrs:
  66
  67  PA_COMMAND_SET_PLAYBACK_STREAM_BUFFER_ATTR
  68  PA_COMMAND_SET_RECORD_STREAM_BUFFER_ATTR
  69
  70 New opcodes for changing sampling rate:
  71
  72  PA_COMMAND_UPDATE_PLAYBACK_STREAM_SAMPLE_RATE
  73  PA_COMMAND_UPDATE_RECORD_STREAM_SAMPLE_RATE
  74
  75 New opcodes for notifications:
  76
  77  PA_COMMAND_PLAYBACK_STREAM_SUSPENDED
  78  PA_COMMAND_CAPTURE_STREAM_SUSPENDED
  79  PA_COMMAND_PLAYBACK_STREAM_MOVED
  80  PA_COMMAND_CAPTURE_STREAM_MOVED
  81
  82 ### v13, implemented by >= 0.9.11
  83
  84 New fields for PA_COMMAND_CREATE_PLAYBACK_STREAM, PA_COMMAND_CREATE_RECORD_STREAM request at the end:
  85
  86  peak_detect (bool)
  87  adjust_latency  (bool)
  88
  89 Replace field "name" for PA_COMMAND_CREATE_PLAYBACK_STREAM, PA_COMMAND_CREATE_RECORD_STREAM at the end:
  90
  91  proplist
  92
  93 Replace field "name" for PA_COMMAND_SET_CLIENT_NAME request at the end:
  94
  95  proplist
  96
  97 On response of PA_COMMAND_SET_CLIENT_NAME:
  98
  99  client_index
 100
 101 New proplist field for sink, source, sink input, source output introspection opcodes and at the end:
 102
 103  proplist
 104
 105 New opcodes for proplist modifications
 106
 107   PA_COMMAND_UPDATE_RECORD_STREAM_PROPLIST
 108   PA_COMMAND_UPDATE_PLAYBACK_STREAM_PROPLIST
 109   PA_COMMAND_UPDATE_CLIENT_PROPLIST
 110   PA_COMMAND_REMOVE_RECORD_STREAM_PROPLIST
 111   PA_COMMAND_REMOVE_PLAYBACK_STREAM_PROPLIST
 112   PA_COMMAND_REMOVE_CLIENT_PROPLIST
 113
 114 New field for PA_COMMAND_PLAY_SAMPLE:
 115
 116   proplist
 117
 118 New field for PA_COMMAND_PLAY_SAMPLE response:
 119
 120   idx
 121
 122 New field for PA_COMMAND_CREATE_PLAYBACK_STREAM at the end:
 123
 124   start_muted
 125
 126 Buffer attributes for PA_COMMAND_CREATE_PLAYBACK_STREAM and
 127 PA_COMMAND_CREATE_RECORD_STREAM may now be 0 for default values.
 128
 129 New field for PA_COMMAND_SET_PLAYBACK_STREAM_BUFFER_ATTR,
 130 PA_COMMAND_SET_RECORD_STREAM_BUFFER_ATTR at the end:
 131
 132   adjust_latency (bool)
 133
 134 new message:
 135
 136   PA_COMMAND_STARTED
 137
 138 ### v14, implemented by >= 0.9.12
 139
 140 new message:
 141
 142   PA_COMMAND_EXTENSION
 143
 144 PA_COMMAND_CREATE_PLAYBACK_STREAM:
 145
 146   bool volume_set at the end
 147
 148 PA_COMMAND_CREATE_RECORD_STREAM, PA_COMMAND_CREATE_PLAYBACK_STREAM:
 149
 150   bool early_requests at the end
 151
 152 New field for PA_COMMAND_SET_PLAYBACK_STREAM_BUFFER_ATTR,
 153 PA_COMMAND_SET_RECORD_STREAM_BUFFER_ATTR at the end:
 154
 155   early_requests (bool)
 156
 157 ### v15, implemented by >= 0.9.15
 158
 159 PA_COMMAND_CREATE_PLAYBACK_STREAM
 160
 161   bool muted at the end
 162
 163 PA_COMMAND_CREATE_PLAYBACK_STREAM, PA_COMMAND_CREATE_RECORD_STREAM:
 164
 165   bool dont_inhibit_auto_suspend at the end
 166
 167 PA_COMMAND_GET_MODULE_INFO_LIST
 168
 169   remove bool auto_unload
 170   add proplist at the end
 171
 172 new messages:
 173
 174   PA_COMMAND_GET_CARD_INFO
 175   PA_COMMAND_GET_CARD_INFO_LIST
 176   PA_COMMAND_SET_CARD_PROFILE
 177
 178   PA_COMMAND_CLIENT_EVENT
 179   PA_COMMAND_PLAYBACK_STREAM_EVENT
 180   PA_COMMAND_RECORD_STREAM_EVENT
 181
 182   PA_COMMAND_PLAYBACK_BUFFER_ATTR_CHANGED
 183   PA_COMMAND_RECORD_BUFFER_ATTR_CHANGED
 184
 185 ### v16, implemented by >= 0.9.15
 186
 187 new messages:
 188
 189   PA_COMMAND_SET_SINK_PORT
 190   PA_COMMAND_SET_SOURCE_PORT
 191
 192 ## v17, implemented by >= 0.9.20
 193
 194 new flag at end of CREATE_PLAYBACK_STREAM:
 195
 196     bool relative_volume
 197
 198 ## v18, implemented by >= 0.9.22
 199
 200 new flag at end of CREATE_PLAYBACK_STREAM:
 201
 202     bool passthrough
 203
 204 ## v19, implemented by >= 0.9.22
 205
 206 New flag at the end of sink input and source output introspection data:
 207
 208     bool corked
 209
 210 ## v20, implemented by >= 1.0
 211
 212 Two new flags at the end of sink input introspection data:
 213
 214     bool has_volume
 215     bool volume_writable
 216
 217 ## v21, implemented by >= 1.0
 218
 219 Changes for format negotiation in the extended API.
 220
 221 New fields PA_COMMAND_CREATE_PLAYBACK_STREAM:
 222
 223     uint8_t n_formats
 224     format_info format1
 225     ...
 226     format_info formatn
 227
 228 One new field in reply from PA_COMMAND_CREATE_PLAYBACK_STREAM:
 229
 230     format_info format
 231
 232 New fields in reply from PA_COMMAND_GET_SINK_INFO (and thus
 233 PA_COMMAND_GET_SINK_INFO_LIST)
 234
 235     uint8_t n_formats
 236     format_info format1
 237     ...
 238     format_info formatn
 239
 240 One new field in reply from PA_COMMAND_GET_SINK_INPUT_INFO (and thus
 241 PA_COMMAND_GET_SINK_INPUT_INFO_LIST)
 242
 243     format_info format
 244
 245 ## v22, implemented by >= 1.0
 246
 247 New fields PA_COMMAND_CREATE_RECORD_STREAM:
 248
 249     uint8_t n_formats
 250     format_info format1
 251     ...
 252     format_info formatn
 253     volume
 254     bool muted
 255     bool volume_set
 256     bool muted_set
 257     bool relative_volume
 258     bool passthrough
 259
 260 One new field in reply from PA_COMMAND_CREATE_RECORD_STREAM:
 261
 262     format_info format
 263
 264 New fields in reply from PA_COMMAND_GET_SOURCE_INFO (and thus
 265 PA_COMMAND_GET_SOURCE_INFO_LIST)
 266
 267     uint8_t n_formats
 268     format_info format1
 269     ...
 270     format_info formatn
 271
 272 Five new fields in reply from PA_COMMAND_GET_SOURCE_OUTPUT_INFO (and thus
 273 PA_COMMAND_GET_SOURCE_OUTPUT_INFO_LIST)
 274
 275     volume
 276     bool mute
 277     bool has_volume
 278     bool volume_writable
 279     format_info format
 280
 281 ## v23, implemented by >= 1.0
 282
 283 New field in PA_COMMAND_UNDERFLOW:
 284
 285     int64_t index
 286
 287 ## v24, implemented by >= 2.0
 288
 289 New field in all commands that send/receive port introspection data
 290 (PA_COMMAND_GET_(SOURCE|SINK)_INFO,
 291 PA_COMMAND_GET_(SOURCE|SINK)_INFO_LIST):
 292
 293     uint32_t available
 294
 295 The field is added once for every port.
 296
 297 ## v25, implemented by >= 2.0
 298
 299 When port availability changes, send a subscription event for the
 300 owning card.
 301
 302 ## v26, implemented by >= 2.0
 303
 304 In reply from PA_COMMAND_GET_CARD_INFO (and thus
 305 PA_COMMAND_GET_CARD_INFO_LIST), the following is added:
 306
 307     uint32_t n_ports
 308
 309 ...followed by n_ports extended port entries, which look like this:
 310
 311     string name
 312     string description
 313     uint32_t priority
 314     uint32_t available
 315     uint8_t direction
 316     proplist
 317     uint32_t n_profiles
 318     string profile_name_1
 319     ...
 320     string profile_name_n
 321
 322 Profile names must match earlier sent profile names for the same card.
 323
 324 ## v27, implemented by >= 3.0
 325
 326 New opcodes:
 327     PA_COMMAND_SET_PORT_LATENCY_OFFSET
 328
 329 New field in the card commands that send/receive port introspection data
 330 PA_COMMAND_GET_CARD_INFO(_LIST)):
 331
 332     int64_t latency_offset
 333
 334 The field is added once for every port.
 335
 336 ## v28, implemented by >= 4.0
 337
 338 New value for encoding format type in format_info
 339 PA_COMMAND_CREATE_(PLAYBACK|RECORDING)_STREAM and its reply,
 340 In reply from PA_COMMAND_GET_(SOURCE|SOURCE_OUTPUT|SINK|SINK_INPUT)_INFO[_LIST],
 341 SUBCOMMAND_SAVE_FORMATS, in reply from SUBCOMMAND_READ_FORMATS[_ALL]
 342
 343     (uint8_t ) PA_ENCODING_MPEG2_AAC_IEC61937 := 6
 344
 345 ## v29, implemented by >= 5.0
 346 #
 347 New field in all commands that send/receive profile introspection data
 348 (PA_COMMAND_GET_CARD_INFO)
 349
 350     uint32 available
 351
 352 The field is added once for every profile.
 353
 354 ## v30, implemented by >= 6.0
 355 #
 356 A new protocol mechanism supported: Two ringbuffers in shared memory.
 357 Pulseaudio fdsem (wrappers around event file descriptors) are used for
 358 signalling new data.
 359 The protocol has a new SHM flag telling whether a SHM memblock is writable
 360 by both sides.
 361
 362 PA_COMMAND_ENABLE_SRBCHANNEL
 363 First sent from server to client, tells the client to start listening on
 364 the additional SHM ringbuffer channel.
 365 This command also has ancillary data (two eventfds attached to it).
 366 Must be directly followed by a memblock which is the ringbuffer memory.
 367 When memblock is received by the client, it acks by sending
 368 PA_COMMAND_ENABLE_SRBCHANNEL back (without ancillary or memblock data).
 369
 370 PA_COMMAND_DISABLE_SRBCHANNEL
 371 Tells the client to stop listening on the additional SHM ringbuffer channel.
 372 Acked by client by sending PA_COMMAND_DISABLE_SRBCHANNEL back.
 373
 374 ## v31, implemented by >= 9.0
 375
 376 Memfd shared-memory support is now added to PulseAudio as an opt-in feature.
 377 Add 'enable-memfd=yes' to daemon's configuration to use memfds, instead of
 378 POSIX shm, by default.
 379
 380 Memfd is a simple memory sharing mechanism, added by the systemd/kdbus
 381 developers, to share pages between processes in an anonymous, no global
 382 registry needed, no mount-point required, relatively secure, manner.
 383
 384 PulseAudio memfd support builds the necessary (but not yet sufficient)
 385 groundwork for a better integration with per-app containers (e.g. xdg-app)
 386
 387 For further details on memfds in general, please check:
 388
 389   https://dvdhrm.wordpress.com/2014/06/10/memfd_create2/
 390   Archived at: http://www.webcitation.org/6gnHTy9Kr
 391
 392 Moreover, for both client and server, the second most-significant bit of
 393 the version tag is now used to flag memfd SHM support. On the way forward,
 394 the two most-significant _bytes_ of the version tag are now also reserved
 395 for flags.
 396
 397 PA_COMMAND_REGISTER_MEMFD_SHMID
 398 New command that can be sent both ways, from client to server and vice versa.
 399 This is needed to transfer a memfd pool's blocks without passing its fd every
 400 time, thus minimizing overhead and avoiding fd leaks.
 401
 402 The registration command above sends a packet with the pool's memfd fd as
 403 ancillary data. Such packet has an ID that uniquely identifies the pool's
 404 memfd memory area. Upon arrival, the other end (client or server) creates a
 405 permanent ID<->memfd mapping.
 406
 407 By doing so, there's need to reference the pool's memfd file descriptor any
 408 further -- just its ID. Thus both endpoints can then quickly and safely
 409 close their memfd file descriptors.
 410
 411 ## v32, implemented by >= 10.0
 412
 413 Enable memfd transport by default.
 414
 415 This protocol bump was only created to mark 9.0 clients. Although they
 416 support memfd transport, such older clients has an iochannel bug that would
 417 break memfd audio if they're run in 32-bit mode over a 64-bit kernel. Thus
 418 influence these buggy libraries to use POSIX shared memory, by signalling
 419 memfd support only to 10.0+ clients.
 420
 421 Check commit 451d1d676237c81 for further details.
 422
 423 ## v33, implemented by >= 13.0
 424
 425 Added two values to the pa_encoding_t enum:
 426
 427     PA_ENCODING_TRUEHD_IEC61937 := 7
 428     PA_ENCODING_DTSHD_IEC61937 := 8
 429
 430 ## v34, implemented by >= 14.0
 431
 432 New fields in the port introspection data (duplicated for all port types:
 433 sink, source and card ports):
 434
 435     string availability_group
 436     uint32 type
 437
 438 ## v35, implemented by >= 15.0
 439
 440 Added new command for communication with objects.
 441
 442 PA_COMMAND_SEND_OBJECT_MESSAGE:
 443 sends a message to an object identified by an object path
 444
 445 parameters:
 446     string object_path - unique path identifying the object
 447     string message - message name
 448     string message_parameters - additional parameters if required (may be
 449                                 NULL, which should be treated the same as an
 450                                 empty string)
 451
 452 The command returns a string, which may be empty or NULL (NULL should be
 453 treated the same as an empty string).
 454
 455 #### If you just changed the protocol, read this
 456 ## module-tunnel depends on the sink/source/sink-input/source-input protocol
 457 ## internals, so if you changed these, you might have broken module-tunnel.
 458 ## Don't forget to test module-tunnel-{source,sink} when pushing protocol
 459 ## changes.