DCA1 specification

DCA1 specification

This is the specification of the DCA1 file format. The DCA file format that was used prior to DCA1 is called metadata-less DCA or simply DCA0.

General information

The recommended file extension for DCA1 files, and all other DCA file formats including DCA0, is .dca.

Magic bytes

All DCA1 files will have the four magic bytes (hexadecimal) 44 43 41 31, ASCII DCA1, at the very beginning. It can be assumed that all future DCA file formats, but not DCA0, have the bytes DCA and another byte that can be any ASCII character at the beginning. (Note that currently the only valid magic byte string for any DCA file is DCA1. Do not assume that it is a valid DCA file just because it has for example DCA@ at the front.)

Metadata

Header

Following the magic bytes, the header for the metadata will be present. It will be a 32-bit little-endian signed integer. It is signed for compatibility purposes, however, the length will never be negative. This integer encodes how many bytes of metadata will follow.

The metadata header can be assumed to never be lower than 2, because that is the minimum length of a JSON object, but it has no maximum size and can theoretically be 2147483647 bytes long.

Data

What follows is a JSON object encoding metadata for the sound file. This is the format this metadata should have, with required attributes marked as such, demonstrated with example data:

{
    // [REQUIRED] General information about this particular DCA file
    "dca": {

        // [REQUIRED] The version of the metadata and audio format.
        // Changes in this version will always be backwards-compatible.
        "version": 1,

        // [REQUIRED] Information about the tool used to encode the file
        "tool": {

            // [REQUIRED] Name of the tool, can be any string
            "name": "dca-encoder",

            // [REQUIRED] The version of the tool used
            "version": "1.0.0",

            // URL where to find the tool at
            "url": "https://github.com/bwmarrin/dca/",

            // Author of the tool
            "author": "bwmarrin"
        }
    },

    // [REQUIRED] Information about the parameters the audio packets are encoded with
    "opus": {

        // [REQUIRED] The opus mode, also called application - "voip", "music", or "lowdelay"
        "mode": "voip",

        // [REQUIRED] The sample rate in Hz.
        "sample_rate": 48000,

        // [REQUIRED] The frame size in bytes.
        "frame_size": 960,

        // [REQUIRED] The resulting audio bitrate in bits per second, or null if the default has not been changed.
        "abr": 64000,

        // [REQUIRED] Whether variable bitrate encoding has been used (true/false).
        "vbr": true,

        // [REQUIRED] The resulting number of audio channels.
        "channels": 2
    },

    // Information about the audio track. 
    // This attribute is optional but it is highly recommended to add whenever possible.
    "info": {

        // Title of the track
        "title": "Out of Control",

        // Artist who made the track
        "artist": "Nothing's Carved in Stone",

        // Album the track is released in
        "album": "Revolt",

        // Genre the track is classified under
        "genre": "jrock",

        // Any comments about the track
        "comments": "Second Opening for the anime Psycho Pass",

        // The cover image of the album/track. See footnote [1] for information about this
        "cover": null
    },
    
    // Information about where the audio data came from
    "origin": {

        // The type of source that was converted to DCA. See footnote [2] for information about this
        "source": "file",

        // Source bitrate in bits per second
        "abr": 192000,

        // Number of channels in the source data
        "channels": 2,

        // Source encoding
        "encoding": "MP3/MPEG-2L3",

        // The URL the source can be found at, or omitted if it wasn't downloaded from the network.
        // Do not put a file path in here, it should be reserved for remote URLs only.
        "url": "https://www.dropbox.com/s/bwc73zb44o3tj3m/Out%20of%20Control.mp3?dl=0"
    },

    // [REQUIRED] A field to put other arbitrary data into. It can be assumed
    // that it always exists, but may be empty. DCA will never use this field internally.
    "extra": {}
}

Footnotes for the metadata

1. The cover image will be a base64-encoded JPEG or PNG image. DCA1 will not do any differentiation between the two, it is up to the user to read the respective magic bytes. The image has no size limit, if necessary it can fill the entire space provided by the maximum length mandated by the metadata header. If there is no image available, it can be null or the attribute can be omitted entirely.
2. The source can be any string, but it is suggested to use file if the source is a local or remote file, and generated if the file has not been converted in any way but has been generated from scratch using a tool.

Audio data

After the metadata, any number of audio packets can follow. It can be assumed that there's always at least one packet available. The packets are structured as follows:

[ header ] [ opus encoded data ]

Header

The header specifies how many bytes of opus encoded data can follow. It is encoded as a 16-bit, signed, little endian integer. It is only signed for compatibility reasons, the length will never be negative. It can be assumed that this header is never zero either.

Opus encoded data

The most important part of a DCA1 file, the audio data, is represented as individual Opus frames encoded using the settings provided in the opus section of the metadata. It is designed to be able to be sent to Discord directly, without having to do further processing (other than adding the header and encrypting it is necessary).

No further assumptions can be made about this data other than it being a valid Opus frame.