diff --git a/sigmf-spec.md b/sigmf-spec.md index f96ce3d..7be7406 100644 --- a/sigmf-spec.md +++ b/sigmf-spec.md @@ -502,9 +502,10 @@ Segment Objects: | ----------------| -------- | ------ | --------------------------------------------------------------------------------------------| | `sample_start` | true | uint | The sample index in the Dataset file at which this Segment takes effect. | | `global_index` | false | uint | The index of the sample referenced by `sample_start` relative to an original sample stream. | -| `header_bytes` | false | uint | The number of bytes preceding a chunk of samples that are not sample data, used for NCDs. | +| `header_bytes` | false | uint | The number of bytes preceding a chunk of samples that are not sample data, used for NCDs. | | `frequency` | false | double | The center frequency of the signal in Hz. | | `datetime` | false | string | An ISO-8601 string indicating the timestamp of the sample index specified by `sample_start`.| +| `capture_tags` | false | array | A list of short form human/machine-readable strings indicating features of this segment. | ##### The `sample_start` Field @@ -613,6 +614,51 @@ The ABNF description is: Thus, timestamps take the form of `YYYY-MM-DDTHH:MM:SS.SSSZ`, where any number of digits for fractional seconds is permitted. +##### The `capture_tags` Field + +This field provides high level contextual information to specific capture +segments. For example, this can flag parts of a Recording containing saturated +data, or can be used to specify portions of data that should be ignored by +subsequent processing stages, or highlight areas that are important. Use of +`capture_tags` differs from annotations in that tags are intended to describe +coarse intermittent features common to all data in a given temporal range, and +many annotations may exist within the segments. There are some situations where +either may be appropriate. + +This field is a list of one or more strings, and in general the most important +tag should be the first list item. This field MAY be used by visualization +software to style a given segment a certain way. + +Standard tags are: `default`, `invalid`, `important`. The tag `default` is +implied in the absense of this field, but an empty list is NOT valid. Any string +is allowed as an entry in this list, but it is RECOMMENDED that strings be +limited to no more than 20 characters. The following example shows this field +used to indicate 1000 samples of saturated data: + +```json +{ + "global": {...}, + "captures": [ + { + "core:sample_start": 0, + "core:capture_tags": ["default"], + "core:frequency": 100000000.0 + }, + { + "core:sample_start": 100000, + "core:capture_tags": ["invalid", "saturated"], + "core:frequency": 100000000.0 + }, + { + "core:sample_start": 101000, + "core:capture_tags": ["default"], + "core:frequency": 100000000.0 + } + ], + "annotations": [] +} +``` + #### Annotations Array The `annotations` value is an array of `annotation segment objects` that diff --git a/sigmf/schema-meta.json b/sigmf/schema-meta.json index 7e21fcd..adad4be 100644 --- a/sigmf/schema-meta.json +++ b/sigmf/schema-meta.json @@ -159,6 +159,11 @@ "required": false, "pattern": "", "help": "An ISO-8601 string indicating the timestamp of the sample index specified by sample_start. (e.g., 2017-02-01T15:05:03.000Z)" + }, + "core:capture_tags": { + "type": "string_list", + "required": false, + "help": "A list of short form human/machine-readable strings indicating features of this segment." } } },