Skip to main content

VLR Connector - GovWorx Standard

GovWorx Standard VLR connector

J
Written by Jordan Lang
Updated over a month ago

GovWorx Data Format Specification

Overview
This document describes the required folder structure and file format for delivering audio recordings and metadata to the GovWorx platform. This specification applies to both radio and telephone call recordings from your communications center.

Folder structure

Hierarchical date-based structure

GovWorx uses a date-based hierarchical folder structure for organizing audio files and metadata. The date hierarchy is based on when the recording started (not when it was exported or saved to disk).

[Root Directory]/
├── YYYY/                    # Year (e.g., 2026)
│   ├── MM/                  # Month (01-12, zero-padded)
│   │   ├── DD/              # Day (01-31, zero-padded)
│   │   │   ├── HH/          # Hour (00-23, zero-padded)
│   │   │   │   ├── [audio files]
│   │   │   │   └── [metadata files]

Example structure

/data/
├── 2026/
│   ├── 02/
│   │   ├── 09/
│   │   │   ├── 14/          # Hour (00-23)
│   │   │   │   ├── call_123456.wav
│   │   │   │   ├── call_123456.csv
│   │   │   │   ├── call_123457.wav
│   │   │   │   ├── call_123457.csv
│   │   │   │   ├── radio_789012.wav
│   │   │   │   └── radio_789012.csv
│   │   │   ├── 15/
│   │   │   │   ├── radio_789013.wav
│   │   │   │   └── radio_789013.csv

File formats

Audio files

  • Format: WAV (Waveform Audio File Format)

  • Extension: .wav

  • Encoding: Standard, non-proprietary audio encodings commonly used in NG911 systems, including but not limited to:

    • PCM (uncompressed)

    • G.711 (μ-law or A-law)

    • G.729

    • G.723.1

  • Channels: Mono or stereo

  • Sample rate: 8000 Hz, 16000 Hz, or higher

  • Bit depth: 16-bit or 24-bit

Important: Files must be standard playable WAV files — no proprietary formats, encryption keys, or additional codecs required. Use filesystem encryption (BitLocker, etc.) for data at rest if required by your environment.

Metadata files

  • Format: CSV (Comma-Separated Values)

  • Extension: .csv

  • Naming convention: Must match the audio filename exactly (e.g., call_001.wav → call_001.csv)

  • Encoding: UTF-8 or ASCII

Each audio file must have a corresponding CSV file containing call metadata.

CSV field specification

Required and optional fields

Field name

Description

Example

call_id

Unique call identifier

550e8400-e29b-41d4-a716-446655440000

channel_name

Position or channel identifier

Position-01

start_time_ms

Call start timestamp (Unix milliseconds)

1707494400000

duration

Call duration in seconds (optional)

180

call_type

Type of call: PHONE or RADIO (optional)

PHONE

agent_id

Agent/dispatcher identifier (optional)

DISP001

caller_number

Receiving party phone number (optional)

555-0100

Sample CSV content

call_id,channel_name,start_time_ms,duration,call_type,agent_id,caller_number 550e8400-e29b-41d4-a716-446655440000,Position-01,1707494400000,180,PHONE,DISP001,555-0100

File naming conventions

Audio files

  • Use descriptive, unique names

  • Include timestamp or sequence number

  • Avoid special characters (use alphanumeric, hyphens, and underscores only)

Examples

call_20260209_140523_001.wav
radio_Position01_1707494400.wav
phone_DISP001_123456.wav

Metadata files

  • Filename must exactly match the corresponding audio filename (excluding extension)

  • Case-sensitive on some systems

Examples

call_123456.wav  →  call_123456.csv
radio_789012.wav →  radio_789012.csv

Critical requirements for proper ingestion

  1. Date hierarchy: Follow the YYYY/MM/DD/HH/ structure exactly with zero-padded values. Use the recording start time to determine the folder path.

  2. Hour folders: Hour folders must be zero-padded (00–23).

  3. File pairing: Each .wav file MUST have a matching [filename].csv in the same directory.

CSV-to-WAV matching

The system matches audio files to metadata using exact filename matching:

  • Audio file: call_123456.wav

  • Metadata file: call_123456.csv

The metadata filename must exactly match the audio filename (excluding extension). This is case-sensitive on some systems.

Best practices

  1. Consistent channel names: Use the same channel identifiers across all recordings.

  2. Complete metadata: Populate all required CSV fields for each recording.

  3. File completeness: Ensure file writes are complete before the Data Agent scans the directory.

  4. Timezone consistency: Be consistent with timezone handling in folder naming (UTC vs local).

Troubleshooting

Missing metadata files

  • Ensure CSV files are generated alongside audio recordings.

  • Verify CSV filename exactly matches the audio filename.

Position mapping errors

  • Confirm position identifiers in CSV match your configured position map.

  • Check for typos or inconsistent naming in the channel_name field.

Audio playback issues

  • Verify WAV files are not corrupted (play them locally).

  • Ensure sample rate and bit depth meet minimum requirements.

  • Check for incomplete file transfers.

Support

For assistance with data format configuration or troubleshooting:

Did this answer your question?