"Fossies" - the Fresh Open Source Software Archive

Member "pulseaudio-13.0/PROTOCOL" (13 Sep 2019, 10967 Bytes) of package /linux/misc/pulseaudio-13.0.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "PROTOCOL": 12.2_vs_13.0.

    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 #### If you just changed the protocol, read this
  431 ## module-tunnel depends on the sink/source/sink-input/source-input protocol
  432 ## internals, so if you changed these, you might have broken module-tunnel.
  433 ## Don't forget to test module-tunnel-{source,sink} when pushing protocol
  434 ## changes.