# HG changeset patch
# User Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
# Date 1593913305 14400
# Node ID 52b73912bf0be0e2e42c8ad328cb81926f54f067
# Parent  63dfe6ae95f6e560a2eb644047fdf40fd89994e1
ckpt

diff -r 63dfe6ae95f6 -r 52b73912bf0b notes.md
--- a/notes.md	Sat May 23 00:30:17 2020 -0400
+++ b/notes.md	Sat Jul 04 21:41:45 2020 -0400
@@ -44,7 +44,8 @@
 such as the center frequency, sample rate, and so on.
 
 It is also possible to include other streams with data that is application
-specific.  For example, meteorological observations or raw GNSS packets.
+specific.  For example, meteorological observations near the antenna or raw
+GNSS packet capture.
 
 Global Metadata Stream
 ----------------------
@@ -53,36 +54,38 @@
 container.  Namely:
 
 * metadata format version number (e.g., 0)
-* generator software ID string (e.g., "SigDigger v0.1.0-23-g828657f")
-* date time of when the container file was created (not necessarily the same
+* `generator`: generator software ID string (e.g., "SigDigger v0.1.0-23-g828657f")
+* `datetime`: date time of when the container file was created (not necessarily the same
   as when the I/Q samples were recorded)
-* hostname?
-* explicit list of metadata stream unique IDs?
+* `hostname`: hostname?
+* `streams`: explicit list of metadata stream unique IDs?
 
 I/Q Data Streams
 ----------------
 
-These are just I/Q samples without any additional headers.
+These are just I/Q samples.
 
 Per-I/Q Stream Metadata Streams
 -------------------------------
 
-* mime type of the I/Q stream (always "application/octet-stream")
-* I/Q data stream unique id
-* I/Q data format (e.g., "cf32" or "cu8")
-* I/Q center frequency in Hz (e.g., 137500000)
-* I/Q sample rate in S/s (e.g., 2560000)
-* I/Q device (e.g., "RTL-SDR v3 00000...")
-* I/Q antenna (e.g., "RTL-SDR dipole")
-* LNA device
-* LNB device
+* `type`: mime type of the I/Q stream (always "application/octet-stream")
+* `ts`: date time of when the packet of samples was created (time of first sample)
+* `iq/samples`: number of samples since last metadata update
+* `iq/uniq`: I/Q data stream unique id
+* `iq/fmt`: I/Q data format (e.g., "cf32" or "cu8")
+* `iq/fc`: I/Q center frequency in Hz (e.g., 137500000)
+* `iq/fs`: I/Q sample rate in S/s (e.g., 2560000)
+* `iq/dev`: I/Q device (e.g., "RTL-SDR v3 00000...")
+* `iq/antenna`: I/Q antenna (e.g., "RTL-SDR dipole")
+* `iq/???`: LNA device
+* `iq/???`: LNB device
 
-* date time of when the packet of samples was created (time of first sample)
-* lat/lon/alt
-* ground speed? azimuth?
-* antenna orientation?
-* LNA gain?
-* LNB freq?
+TODO: what else?  should some of the following be separate streams?
+* ``: lat/lon/alt
+* ``: ground speed? azimuth?
+* ``: antenna orientation?
+* ``: LNA gain?
+* ``: LNB freq?
 
 Misc Data Streams
 -----------------
@@ -94,12 +97,9 @@
 Per-Misc Data Stream Metadata Streams
 -------------------------------------
 
-* mime type of the data stream (e.g., XXX)
+* mime type of the data stream (e.g., TODO)
 * optional application specific key-value pairs
 
-* optional application specific key-value pairs
-
-
 TODO: what's in a packet? what's in a stream? what streams are there?
 
 A typical session will contain only three streams:
@@ -150,20 +150,20 @@
 
 ```
 sigdigger_20200520_010415Z_1024000_137500000_float32_iq.raw
-sigdigger_20200520_010415Z_1024000_137500000_float32_iq.ogg
+sigdigger_20200520_010415Z_1024000_137500000_float32_iq.meta
 ```
 
-The `.raw` contains the samples as before.  The `.ogg` file contains the
-remaining streams serialized into an Ogg format.  This would yield all the
-benefits of having a richer format without the initial incompatibility with
-other software.
+The `.raw` contains the samples as before.  The `.meta` file contains the
+remaining streams serialized into structured metadata format (e.g., Ogg +
+CBOR).  This would yield all the benefits of having a richer format without
+the initial incompatibility with other software.
 
 
 Other Existing Container Formats
 --------------------------------
 
 Here are some other existing container file formats that I looked at and
-decided that they are too cumbersome for some reason.
+decided that they are too cumbersome for one or more reasons.
 
 * RIFF: 32-bit file sizes, very messy spec
 * RF64: 64-bit version of RIFF, very messy spec