Documentation/FTL-Format.md

@@ -8,16 +8,47 @@ struct Header {
 };
 ```
 
+```c++
+struct IndexHeader {
+    int64_t reserved[8];
+};
+```
+
 All subsequent data is MsgPack encoded. All subsequent data consists of a tuple of StreamPacket and Packet pairs (in that order). These packets specify stream, channel and codec information, allowing different kinds of data to be included in a stream.
 
+```c++
+struct StreamPacket {
+    int64_t timestamp;
+    uint8_t streamID;
+    uint8_t channel_count;
+    ftl::codecs::Channel channel;
+};
+```
+
+A stream packet locates a data packet within the overall context. It identifies which stream it belongs to and which channel within that stream, along with a timestamp to position it. `channel_count` is used when indicating that multiple channels constitute a completed frame. This may be 0 if a packet does not need to be considered atomically a part of the complete frame.
+
+```c++
+struct Packet {
+    ftl::codecs::codec_t codec;
+    ftl::codecs::definition_t definition;
+    uint8_t block_total;
+    uint8_t block_number;
+    uint8_t flags;
+    std::vector<uint8_t> data;
+};
+```
+
+The packet structure provides details relevant to the encoding. `codec` is one of: JPG, PNG, H264, HEVC, JSON, MSGPACK, RAW and some others. `definition` identifies one of a predefined set of resolutions such as 1920x1080. `block_total` is the total number of packets that make up the current frame for the current channel in the current stream. Usually `block_total` is 1 unless a concurrent chunking encoder is used that then sends those chunks immediately. `block_number` is the sequence number for the current block and will always be 0 if `block_total` is 1. `flags` should be 0 or set to codec specific values. `data` contains the raw encoded data for the frame.
+
 ### Version 0
-No longer valid.
+No longer valid. Did not have the 64 byte index header and had different packet structures.
 
 ### Version 1
 * Additional fields in StreamPacket and Packet structures. Not backwards compatible.
 
 ### Version 2
-* Add 64 bytes of reserved space after header
+* Add 64 bytes of reserved space after header. To be used for indexing.
+* Packet flags is unused in this version.
 
 ### Version 3
 * Set packet flags to 0 or: