mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-11-02 09:01:50 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
pipewire/doc/design.txt

212 lines
8.8 KiB
Text
Raw Normal View History

doc: add simple design doc
2015-08-21 11:46:29 +02:00
Pinos
-----
The idea is to make a DBus service where you can provide
and consume media to/from.
Some of the requirements are:
- must be efficient for raw video using fd passing
- must be able to provide media from any process
- streaming media only (no seeking)
- policy to restrict access to devices and streams
Although an initial goal, the design is not limited to raw video
only and should be able to handle compressed video and other
streamable media as well.
The design is in some part inspired by pulseaudio, hence its original
name. We however are not concerned with playback of any of the media,
this should be handled by a separate consumer rendering the media to
a specific output device.
DBus protocol
-------------
The main daemon is registered on the session bus with name: org.pinos
Various Source1 objects are registered in the server based on the available
sources of content. Source1 has properties and has format descriptions of
what it can provide.
First a client needs to register with pinos by calling
org.pinos.Daemon1.ConnectClient(). This creates a new Client1 object that
the client must use for further communication.
doc updates
2015-09-30 13:00:14 +02:00
A client can then do org.pinos.Client1.CreateSourceOutput() to create a
doc: add simple design doc
2015-08-21 11:46:29 +02:00
new SourceOutput1 to retrieve data from a source. It can specify a source
explicitly or let the server choose a source. The client must provide a list
of formats it can handle along with extra properties that can help with
selecting an appropriate source.
A client can then call org.pinos.SourceOutput1.Start() to negotiate the final
media format and start the data transfer. A new fd is returned to the client
along with the negotiated format and properties.
All further media transport is then performed on the fd. The client will read
from the fd to get data and metadata from the server. The wire format is
generic and extensible and allows for inline serialized events such as
property changes and format changes.
Wire
----
Fixed header
doc updates
2015-09-30 13:00:14 +02:00
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Version : 4 bytes : message version
Length : 4 bytes : total message length
doc: add simple design doc
2015-08-21 11:46:29 +02:00
Followed by 1 or more type-length-data sections
doc updates
2015-09-30 13:00:14 +02:00
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Len ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Data .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
doc: add simple design doc
2015-08-21 11:46:29 +02:00
<type> : 1 byte
add continuation packet Add continuation type packet that would make it possible to send commands using a piece of shared memory.
2015-08-31 17:10:44 +02:00
<length> : variable length, 7 bits, high bit is continuation marker
Rework the wire protocol Send a command stream over the socket. Implement a new buffer object that holds the data and commands. Make iterator and builders to parse and construct buffers. Rework gstreamer elements to use new API for creating and parsing buffers. Add _release_buffer to notify a stream when we are done processing the buffer. This will eventually go all the way to the server and will allow us to do more complicated buffer management.
2015-08-24 16:41:04 +02:00
<data> : <length> bytes, see below for contents based on <type>
doc: add simple design doc
2015-08-21 11:46:29 +02:00
Types:
add continuation packet Add continuation type packet that would make it possible to send commands using a piece of shared memory.
2015-08-31 17:10:44 +02:00
1: continuation section
doc updates
2015-09-30 13:00:14 +02:00
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Offset ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Size ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
add continuation packet Add continuation type packet that would make it possible to send commands using a piece of shared memory.
2015-08-31 17:10:44 +02:00
Rest of the commands can be found in the shared memory region at
@offset and @size. A shared memory region is negotiated when the client
connects to the server.
<offset> : 8 bytes : offset
<size> : 8 bytes : size
2: header
More work on wire protocol Make separate payload for the header. Make release-fd payloads capture_buffer -> peek_buffer to avoid a copy remove release-buffer, we really need to release each fd in the buffer separately. provide_buffer -> send_buffer so that we can also use this to send the release-fd messages. in pinossrc, send back release-fd messages when the fd is no longer in use.
2015-08-31 16:47:32 +02:00
Header for payload
doc updates
2015-09-30 13:00:14 +02:00
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| seq |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| PTS ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| DTS-offset ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
More work on wire protocol Make separate payload for the header. Make release-fd payloads capture_buffer -> peek_buffer to avoid a copy remove release-buffer, we really need to release each fd in the buffer separately. provide_buffer -> send_buffer so that we can also use this to send the release-fd messages. in pinossrc, send back release-fd messages when the fd is no longer in use.
2015-08-31 16:47:32 +02:00
<flags> : 4 bytes : buffer flags
<seq> : 4 bytes : sequence number
<pts> : 8 bytes : presentation time
<dts-offset> : 8 bytes : dts-offset
add continuation packet Add continuation type packet that would make it possible to send commands using a piece of shared memory.
2015-08-31 17:10:44 +02:00
3: fd-payload section
Rework the wire protocol Send a command stream over the socket. Implement a new buffer object that holds the data and commands. Make iterator and builders to parse and construct buffers. Rework gstreamer elements to use new API for creating and parsing buffers. Add _release_buffer to notify a stream when we are done processing the buffer. This will eventually go all the way to the server and will allow us to do more complicated buffer management.
2015-08-24 16:41:04 +02:00
add continuation packet Add continuation type packet that would make it possible to send commands using a piece of shared memory.
2015-08-31 17:10:44 +02:00
Used to send a block of data between client and server. The type of fd and
the possible operations on it are negotiated when the client connects.
Rework buffer API a little Use BufferIter and BufferBuilder instead of Packet* Make separate method to set the header so you can set it later and not only at builder init time. Add method to clear the builder if you want to abort. Add method to add fd to builder instead of in _add_fd_payload. This would make it easier to add multiple fd-payloads using data from the same fd. Pass PinosPacketFDPayload to add_fd_payload to make it symetric with the parsing code. We should be able to get the size from the VERSION passed when the builder was made. Add ideas about releasing the fds back to the server.
2015-08-26 12:46:28 +02:00
doc updates
2015-09-30 13:00:14 +02:00
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| id |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| offset ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| size ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| fd-index |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
More work on wire protocol Make separate payload for the header. Make release-fd payloads capture_buffer -> peek_buffer to avoid a copy remove release-buffer, we really need to release each fd in the buffer separately. provide_buffer -> send_buffer so that we can also use this to send the release-fd messages. in pinossrc, send back release-fd messages when the fd is no longer in use.
2015-08-31 16:47:32 +02:00
<id> : 4 bytes : id of the fd-payload
<offset> : 8 bytes : offset
<size> : 8 bytes : size
<fd-index> : 4 bytes : index of fd
Rework the wire protocol Send a command stream over the socket. Implement a new buffer object that holds the data and commands. Make iterator and builders to parse and construct buffers. Rework gstreamer elements to use new API for creating and parsing buffers. Add _release_buffer to notify a stream when we are done processing the buffer. This will eventually go all the way to the server and will allow us to do more complicated buffer management.
2015-08-24 16:41:04 +02:00
add continuation packet Add continuation type packet that would make it possible to send commands using a piece of shared memory.
2015-08-31 17:10:44 +02:00
4: release fd-payload
Rework buffer API a little Use BufferIter and BufferBuilder instead of Packet* Make separate method to set the header so you can set it later and not only at builder init time. Add method to clear the builder if you want to abort. Add method to add fd to builder instead of in _add_fd_payload. This would make it easier to add multiple fd-payloads using data from the same fd. Pass PinosPacketFDPayload to add_fd_payload to make it symetric with the parsing code. We should be able to get the size from the VERSION passed when the builder was made. Add ideas about releasing the fds back to the server.
2015-08-26 12:46:28 +02:00
Release a fd-payload with <id>
doc updates
2015-09-30 13:00:14 +02:00
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| id |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
More work on wire protocol Make separate payload for the header. Make release-fd payloads capture_buffer -> peek_buffer to avoid a copy remove release-buffer, we really need to release each fd in the buffer separately. provide_buffer -> send_buffer so that we can also use this to send the release-fd messages. in pinossrc, send back release-fd messages when the fd is no longer in use.
2015-08-31 16:47:32 +02:00
<id> : 4 bytes : the id number of the released fd-payload
doc: add simple design doc
2015-08-21 11:46:29 +02:00
add continuation packet Add continuation type packet that would make it possible to send commands using a piece of shared memory.
2015-08-31 17:10:44 +02:00
5: format change
Perform an in-band format change. The following data blocks will be in this
new format.
doc: add simple design doc
2015-08-21 11:46:29 +02:00
doc updates
2015-09-30 13:00:14 +02:00
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| id | format ..... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ...... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
More work on wire protocol Make separate payload for the header. Make release-fd payloads capture_buffer -> peek_buffer to avoid a copy remove release-buffer, we really need to release each fd in the buffer separately. provide_buffer -> send_buffer so that we can also use this to send the release-fd messages. in pinossrc, send back release-fd messages when the fd is no longer in use.
2015-08-31 16:47:32 +02:00
<format-id> : 1 byte : format id
<format> : 0-terminated : contains serialized format
doc: add simple design doc
2015-08-21 11:46:29 +02:00
add continuation packet Add continuation type packet that would make it possible to send commands using a piece of shared memory.
2015-08-31 17:10:44 +02:00
6: property changes
Notify a property change.
doc: add simple design doc
2015-08-21 11:46:29 +02:00
doc updates
2015-09-30 13:00:14 +02:00
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| key .... .. |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ...... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| value .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ...... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
doc: add simple design doc
2015-08-21 11:46:29 +02:00
<key> : 0-terminated : key
<value> : 0-terminated : value
doc updates
2015-09-30 13:00:14 +02:00
... : more key/values to fill length, 0 key or
message length is end
doc: add simple design doc
2015-08-21 11:46:29 +02:00
Reference in a new issue Copy permalink