Voicegram Recording 1.0 Specification

The voicegram format of GNOME Voice: a short Ogg Vorbis recording and a .voice XML descriptor that says who spoke, where, and where the recording can be heard.

Version: 1.0
Date: 15 October 2026
Editor: Ole Kristian Aamot
Status: Stable. Describes the format written by GNOME Voice 51.0 and Voicegram 0.1.0.
Schema: voice.rnc (RELAX NG compact) · voice.rng (RELAX NG XML) · example.voice

1Conventions

The key words must, must not, should, should not and may are to be read as described in RFC 2119 and RFC 8174. A producer writes voicegrams (for example GNOME Voice or Voicegram when recording). A consumer reads them (a map client, a player, a server).

2The voicegram

A voicegram is a pair of files that belong together:

Part	Format	Extension	Media type
Audio stream	Ogg Vorbis	`.ogg`	`audio/ogg`
Descriptor	XML 1.0, UTF-8	`.voice`	`application/x-gnome-voice+xml`

The descriptor names the speaker, the place on the map, and one or more addresses where the audio stream can be fetched. A voicegram is public once its descriptor points at a stream address others can reach.

The x- media type is not registered with IANA. Servers should send it for .voice files; consumers must also accept application/xml and text/xml.

3The audio stream

The stream must be Vorbis audio in an Ogg container (RFC 3533, Vorbis I).
Producers should record at 44.1 kHz. Mono is recommended for speech; stereo is allowed.
Voicegrams are short messages. Producers should keep public voicegrams under one minute, and servers may refuse longer or larger streams.
Consumers must identify the stream by content (the OggS capture pattern and a Vorbis identification header), not by file name alone.

4The .voice descriptor

A descriptor is a well-formed XML 1.0 document encoded as UTF-8, without a namespace. The smallest valid descriptor, as written by GNOME Voice 51.0:

<?xml version="1.0" encoding="UTF-8"?>
<voice version="51.0">
  <station name="Ole Kristian Aamot" uri="https://www.gnomevoice.org/">
    <location lat="59.9139" lon="10.7522">Oslo</location>
    <stream>https://voice.example.org/voicegrams/GNOME.ogg</stream>
  </station>
</voice>

With the optional elements, as written by Voicegram 0.1.0 (example.voice):

<?xml version="1.0" encoding="UTF-8"?>
<voice version="51.0">
  <station name="Ole Kristian Aamot" uri="https://www.gnomevoice.org/">
    <location lat="59.910900" lon="10.752500">Oslo</location>
    <stream>https://voice.example.org/voicegrams/streams/5f4e…5338.ogg</stream>
    <title>Morning at Jernbanetorget</title>
    <date>2026-10-15T07:40:00+02:00</date>
    <duration>12.4</duration>
  </station>
</voice>

4.1`<voice>` — root element

version	Required. The GNOME Voice format level the file follows. Files following this specification must use `51.0`. Consumers must not reject a file only because the value is different.
Content	Exactly one `<station>`.

4.2`<station>` — the speaker

name	Required. The speaker's name as it is shown to the public. May be empty for an anonymous voicegram.
uri	Optional. An absolute `http` or `https` address for the speaker or station.
Content	In this order: one `<location>`; one or more `<stream>`; then optionally `<title>`, `<date>` and `<duration>`.

4.3`<location>` — the place on the map

lat	Required. Latitude in decimal degrees, WGS 84, from −90 to 90.
lon	Required. Longitude in decimal degrees, WGS 84, from −180 to 180.
Content	Optional human-readable place name, such as `Oslo`.

The position is where the voicegram is placed on the map. That is normally where it was recorded, but the speaker may place it elsewhere. Producers should write no more than six decimals (about 0.1 m).

4.4`<stream>` — where to listen

Content: an absolute URI of the Ogg Vorbis stream. Public voicegrams must use http or https. A local file not yet shared may use a file URI. When there are several <stream> elements they are alternative addresses for the same recording, in order of preference: consumers play the first one that works.

4.5Optional elements

<title>	A short title chosen by the speaker. Producers should keep it under 80 characters.
<date>	When the voicegram was recorded, as an ISO 8601 / XML Schema `dateTime` with a time zone offset, e.g. `2026-10-15T07:40:00+02:00`.
<duration>	Length of the recording in seconds, as a decimal number.

4.6Extending the format

Consumers must ignore elements and attributes they do not know, so later versions can add information without breaking existing software. Producers must not change the meaning of the elements defined here.

5Collections

A list of voicegrams, for example a server's answer to “what is in this part of the map”, is a <voicegrams> root element holding zero or more <voice> elements, each exactly as in a single descriptor:

<voicegrams>
  <voice version="51.0">…</voice>
  <voice version="51.0">…</voice>
</voicegrams>

A consumer that cannot use one entry (for example because it has no location) should skip it and keep the rest.

6Files on disk

The two files of a voicegram share a base name: name.ogg and name.voice.

Software	Where it saves
GNOME Voice 51.0	`GNOME.ogg` and `GNOME.voice` in the Music folder
Voicegram 0.1.0	`voicegram-YYYYMMDD-HHMMSS.ogg` and `.voice` in `Music/Voicegram/`

7Publishing over HTTP

This specification defines the files, not the transport. Each server documents its own HTTP interface; what they have in common is that the stream is published at a public address and the descriptor's <stream> points to it.

Server	Interface
Voice Server 1.0.0	Exposes a `/voicegrams` listing; uploaded with `gnome-voice-send`. Documented in `PROTOCOL.md` in the server tarball.
Voicegram server 0.1.0	See below.

7.1Voicegram server interface

Request	Result
`POST /voicegrams/streams` body: Ogg Vorbis	`201`, `Location`: the public stream URL
`POST /voicegrams` body: `.voice` naming that stream	`201`, the published descriptor; `Location`: its URL
`GET /voicegrams?bbox=minlon,minlat,maxlon,maxlat`	A `<voicegrams>` collection, newest first
`GET /voicegrams/<id>.voice`	One descriptor
`GET /voicegrams/streams/<id>.ogg`	The audio stream

A bbox whose minlon is greater than maxlon crosses the 180th meridian.

8Conformance

A conforming descriptor is valid against the schema in section 11 and follows the rules of sections 3 and 4.

A conforming producer writes only conforming descriptors and Ogg Vorbis streams, and keeps both files of a pair under the same base name.

A conforming consumer reads every conforming descriptor, ignores unknown elements and attributes (4.6), and follows the security rules in section 10.

9Privacy

A shared voicegram makes a person's voice, name and position public. Producers:

must show the position and the public name before anything is shared;
should let the speaker move the voicegram away from the exact spot where it was recorded;
should allow an empty or chosen name rather than requiring a real name.

Servers should offer a way to remove voicegrams and to report abuse.

10Security

Descriptors must not contain a document type declaration. Consumers must reject documents with <!DOCTYPE or entity declarations and must not fetch external entities.
Consumers should limit descriptor size (16 KiB is ample for one voicegram) and only follow http, https and, for local files, file stream URIs.
Consumers should not play voicegrams without the user asking.
Servers should check that uploaded audio really is Ogg Vorbis and should rate-limit uploads.

11Schema

Normative RELAX NG schema. Download: voice.rnc · voice.rng. Validate with xmllint --relaxng voice.rng file.voice.

datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes"

start = voice | voicegrams

voice = element voice {
  attribute version { text },
  station
}

voicegrams = element voicegrams { voice* }

station = element station {
  attribute name { text },
  attribute uri { xsd:anyURI }?,
  location,
  stream+,
  element title { text }?,
  element date { xsd:dateTime }?,
  element duration { xsd:decimal { minInclusive = "0" } }?
}

location = element location {
  attribute lat { xsd:decimal { minInclusive = "-90" maxInclusive = "90" } },
  attribute lon { xsd:decimal { minInclusive = "-180" maxInclusive = "180" } },
  text
}

stream = element stream { xsd:anyURI }

The schema checks one version of the format strictly. A consumer applying rule 4.6 accepts more than the schema does; a producer must stay within it.

12History

1.0	15 October 2026. First written specification of the format used by GNOME Voice (version attribute `51.0`). Adds the optional `<title>`, `<date>` and `<duration>` elements, collections, conformance, privacy and security rules.