Vital File Format

Vital File Format Specification

Introduction

• The vital file is a binary file format used by VitalRecorder for saving vital signs and waveforms.
• It is a single gzip-compressed binary file starting with 1F 8B 08 00.
• It contains a header and a body part.
• Multi-byte variables are encoded using little-endian byte order.
• All data structures are aligned on 1-byte boundaries.
• Caution: Some compilers use 4-byte alignment implicitly. For Visual Studio, use #pragma pack(push, 1) / #pragma pack(pop).

---

Data Formats

String

• Strings are encoded in UTF-8.
• A string field consists of a 4-byte length (excluding the length field itself) followed by a character array of the specified length.
• Caution: The string does not include a trailing NULL (\0) character.

Time

• Times are stored in UTC.
• UTC can be converted to local time using the time zone bias (offset) in the header:
• UTC = local_time + tzbias
• All time values are represented as the number of seconds since 1970-01-01 00:00:00 UTC in IEEE 754 double format.
• This is compatible with Unix timestamps and convenient for arithmetic operations.
• The decimal part represents sub-second precision. Because the Unix timestamp for year 2020 is approximately 1,606,780,800 (requiring 31 bits for the integer part) and IEEE 754 double has 52 bits of fraction, approximately 21 bits remain for sub-second representation, giving roughly 1 microsecond resolution.

---

Header

The total length of the header is 10 + headerlen bytes.

The vital file does not include the number or length of tracks in the header. You must parse the body to discover tracks and records. This is because VitalRecorder cannot know when recording will stop, and tracks can be added at any time during recording.

The header can be extended by increasing headerlen. Parsers should use headerlen to determine which optional fields are present.

Time Zone Conversion Example

time_t t = (time_t)(dt - tzbias * 60);  // UTC -> local time in seconds
struct tm *ptm = gmtime(&t);            // seconds -> year, month, day, hour, minute, second

Packed Mode (packed = 1)

When packed is set to 1, the file uses packed storage format with these guarantees:

• WAV tracks: All waveform records for each track are merged into a single REC. Gaps between consecutive records are filled with NaN samples (see table below). This allows direct sample access by index: sample_time = trk_dtstart + sample_index / srate.
• NUM/STR tracks: Records for each track appear consecutively and are sorted by time.
• Track grouping: All RECs belonging to the same track are stored consecutively (track by track).
• TRKINFO fields: Each TRKINFO includes reclen, dtstart, and dtend for the track.

NaN Values by Format Type

---

Body

The body is a sequence of packets. Since packet lengths are not constant, there is no way to directly index a specific packet without reading sequentially. However, you can skip unwanted packet types using the datalen field.

Packet Structure

Packet Types

---

DEVINFO (type = 9)

Stores device information. Must be saved before the corresponding devid is used in any TRKINFO.

• If devid is 0, it indicates VitalRecorder itself (e.g., filter-generated tracks, event markers).
• A new DEVINFO can appear for the same devid within a file; the new values overwrite the previous ones.
• devid and trkid are meaningful only within the same file.
• VitalRecorder assigns the same devid to the same device type connected to the same physical port, even across program restarts.

---

TRKINFO (type = 0)

Stores track information. Must appear before the first REC with the corresponding trkid. Records with an unknown trkid should be ignored.

• Tracks are identified by trkid, a 2-byte integer. The numeric value itself has no inherent meaning and may change between program executions.
• Track display order is determined by order of appearance and the CMD_TRK_ORDER command, not by trkid value.
• A track with devid = 0 and name EVENT is treated specially: it is displayed in the event bar rather than as a separate track.

Record Format (recfmt)

---

REC (type = 1)

Stores time-stamped data (measured samples, sample arrays, or strings).

WAV Record Values

Samples continuously measured from time dt, stored as an array. The sample rate and data type come from the TRKINFO.

NUM Record Values

STR Record Values

---

CMD (type = 6)

Command packets. Unknown commands should be skipped using the packet's datalen.

CMDTRKORDER (cmd = 5)

Defines the display order of tracks.

CMDRESETEVENTS (cmd = 6)

Removes all event markers prior to this command. No additional data.

---

Monitor Type Codes (montype)

The montype field in TRKINFO specifies the physiologic meaning of the track. This enables applications to identify and display parameters consistently regardless of track naming conventions.

ECG

Arterial Blood Pressure (Invasive)

Pulse Oximetry (PLETH)

Respiration

CO2

Non-Invasive Blood Pressure

Temperature

Central Venous Pressure

EEG / Brain Monitoring

Airway

Anesthetic Agents

Drug Infusion

Cerebral Oximetry

Additional EEG

Advanced Pulse Oximetry

Pulmonary Artery

Femoral Artery

Intracranial Pressure

Neuromuscular Monitoring

SKNA (Skin Sympathetic Nerve Activity)

Miscellaneous

Additional Waveforms

Fetal Monitoring

Filter Outputs

Note: Applications should treat unknown montype values gracefully; new types may be added in future versions.