Filenames for audio files

This guide contains recommendations for naming audio files containing ecoacoustic recordings.

One format makes it easier for everyone to write software once that works for everyone. It encourages collaboration and interoperability. This is important for researchers, platforms, and tools alike.

Recommended Format #

We have a recommended format that you should use if you need to make new audio files. However, there are many existing formats that our software recognises. See the Alternative formats section.

Our recommended format¹ is:

{Datestamp}[_{SiteName}][…_{Other Components}].{Extension}

Where:

• Datestamp is the date and time the recording started. See the Datestamps section for details.
• SiteName is an optional human readable name for the recording location.
• Other Components are optional additional information, such as location. See the Components section for details.
• Extension is a normal file extension. See the Extensions section for details.

Valid examples of this format include:

20170625T102105Z_SiteName_123456.flac
20170625T102105+1000_Oxley-creek_-12.345+127.789.wav
20170625T102105.123456+0930.wav

We’ll explain each part of the format below.

[!Note] Most tools and platforms don’t output filenames in this format yet. However, Ecosounds and EMU are two tools that do.

The choices made in this document are designed, in priority order, to:

1. be safe for use in most operating systems and shells
2. follow existing standards where possible
3. be easy to read by humans
4. be easy to parse by computers
5. be compact
6. be naturally sortable

Special characters #

Filenames MUST NOT contain special characters, including those that are commonly interpreted by shells (like Bash, PowerShell, or CMD).

Filenames:

• MUST NOT contain any of the following characters:
  • Any non printable characters (e.g. null, backspace, tab, newline, etc)
  • * (asterisk)
  • ? (question mark)
  • [ (left square bracket)
  • ] (right square bracket)
  • { (left curly brace)
  • } (right curly brace)
  • \ (backslash)
  • / (forward slash)
  • | (pipe)
• SHOULD NOT contain:
  • Any leading or trailing whitespace
  • Single (') or double (") quotes
  • Spaces
• MAY contain:
  • Alphanumeric characters (A-Z, a-z, 0-9)
  • Hyphens (-)
  • Underscores (_)
  • Periods (.)

Spaces MAY be used, but are NOT RECOMMENDED. If a filename needs to be converted to remove spaces, then spaces SHOULD be replaced with hyphens (-).

For example:

- 20170625T102105_Oxley creek.wav
+ 20170625T102105_Oxley-creek.wav

Extensions #

A filename MUST end with a file extension, and SHOULD be and extension used for audio. For example:

• .flac
• .wav
• .mp3

An extension MUST match the actual file format of the audio file.

Components #

Each piece of information in a filename is called a component. You MUST separate components of the filename with an underscore (_). The sole exception to this is the extension component which is separated with a period (.).

For example:

- 20170625T102105Oxley creek.wav
+ 20170625T102105_Oxley-creek.wav

You MAY include as many additional components as you like, in any order, separated by underscores (_), however the minimum requirement is to include the datestamp and extension components.

Datestamps #

The most important part of a filename is the date and time the recording started. We recommend using an ISO8601 format for all date and time information (everywhere, not just in filenames). ISO8601 is an international standard for the representation of dates and times.

For filenames though, you MUST use the basic format of ISO8601, which does not include any separators (e.g. hyphens or colons). This produces a more compact datestamp and avoids any issues with special characters (mainly :) in filenames.

Filenames SHOULD contain a UTC offset (see below) to avoid ambiguity about the time the recording started. Filenames MAY use Z to indicate UTC+0.

Examples of the recommended format follow:

20250990T033235Z.flac
20250990T033235.123456+0930.wav
20250990T033235-0430.wav

Variations of this format MAY omit the UTC offset, e.g. 20170625T102105.flac but this is NOT RECOMMENDED because the datestamp becomes ambiguous.

Precise format #

The precise format¹ for the date and time is: YYYYMMDDThhmmss[.SSSSSS][(Z|(+|-)hhmm)]. Where:

Locations #

It is RECOMMENDED to encode location information inside the metadata of audio files rather than in filenames.

However, if you do need to encode location, then filenames MUST use ISO6709:H without a trailing solidus to represent locations in filenames. We omit the trailing solidus (/) to avoid special characters in filenames.

The precise format¹ is: (+|-)<Latitude>(+|-)<Longitude>[(+|-)<Altitude>][<CRS>], where:

• Implementers MUST use only decimal degrees.
  • DO NOT use degrees, minutes, seconds.
• Implementers MUST use a leading sign (+ or -) for both latitude and longitude.
• Consumers MUST assume the WGS84 datum, unless otherwise specified in the metadata.
• Altitude MAY be included, but is not required.
  • If included, altitude MUST be in meters above sea level, with a leading sign (+ or -).
• Latitude MUST be formatted with a leading sign (+ or -).
• Latitude MUST be formatted with 2 digits before the decimal point, including a leading zero if necessary.
• Longitude MUST be formatted with a leading sign (+ or -).
• Longitude MUST be formatted with 3 digits before the decimal point, including a leading zeros if necessary.
• Altitude MUST be formatted with a leading sign (+ or -) when included.
• The CRS SHOULD be presented as a EPSG code, prefixed with CRS
  • e.g. CRSWGS_84 for WGS84

For example, an audio file with the latitude -39.5336, and longitude of +131.2711 would be encoded in the filename as:

-39.533600+131.271100

Valid examples in filenames include:

20170625T102105+1000_-12.345000+127.456000.wav
20170625T102105+1000_+02-009.wav
20170625T102105+1000_-12.345-127.456+30.wav
20170625T102105+1000_-12.345000+127.456000+30CRSWGS_84.wav
20170625T102105+1000_+0+0.flac

Alternative Date & Time Formats #

Open Ecoacoustics maintains a tool, EMU, that can parse a variety of date and time formats from filenames. The full list of supported formats can be found in EMU’s test fixtures: https://github.com/QutEcoacoustics/emu/blob/master/test/Fixtures/FileNameParsingFixtures.csv

Alternative formats SHOULD NOT be used, but we recognise that many formats are already in use. EMU supports the following alternative formats and can convert² them to the recommended format.

End Date times #

So far only one manufacturer (Frontier Labs) encodes both a start and end date in their filenames. They do this so their localisation software can determine what direction from a recorder a sound was made.

You SHOULD NOT use this format, but we recognise it is in use. Instead we RECOMMEND embedding the end date in the audio file’s metadata.

If you need to parse it, then EMU can parse both the start and end datestamps.

The format prefixes the start date with S and the end date with E.

The datestamps produced in this format are otherwise well formatted with respect to the recommended format.