share/man/man4/au.4

   1 '\" te
   2 .\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH AU 4 "Jan 15, 2001"
   7 .SH NAME
   8 au \- AU audio file format
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB#include <audio/au.h>\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 An AU audio file is composed of three parts: a header, an optional description
  19 field, and a contiguous segment of audio data. The header is 24 bytes, and the
  20 description field is at least 4 bytes. Therefore, the offset for most AU files
  21 is 28 bytes. However, some people store additional data in the AU header.
  22 .sp
  23 .LP
  24 The AU audio structure members and audio data are stored big endian. That is,
  25 it starts with the most significant byte, regardless of the native byte order
  26 of the machine architecture on which an application may be running. Therefore,
  27 multi-byte audio data may require byte reversal for proper playback on
  28 different processor architectures. See the macro section for properly reading
  29 and writing the AU audio structure members.
  30 .sp
  31 .LP
  32 The AU header is defined by the following structure:
  33 .sp
  34 .in +2
  35 .nf
  36 struct au_filehdr {
  37    uint32_t au_magic;       /* magic number (.snd) */
  38    uint32_t au_offset;      /* byte offset to start of audio data */
  39    uint32_t au_data_size;   /* data length in bytes */
  40    uint32_t au_encoding;    /* data encoding */
  41    uint32_t au_sample_rate; /* samples per second */
  42    uint32_t au_channels;    /* number of interleaved channels */
  43 };
  44 typedef struct au_filehdr au_filehdr_t;
  45 .fi
  46 .in -2
  47
  48 .sp
  49 .LP
  50 The \fBau_magic\fR field always contains the following constant for an AU audio
  51 file:
  52 .sp
  53 .in +2
  54 .nf
  55 AUDIO_AU_FILE_MAGIC   ( 0x2e736e64 ) /* ".snd" */
  56 .fi
  57 .in -2
  58
  59 .sp
  60 .LP
  61 The \fBau_offset\fR field contains the length of the audio file header plus the
  62 variable length info field. Consequently, it can be interpreted as the offset
  63 from the start of the file to the start of the audio data.
  64 .sp
  65 .LP
  66 The \fBau_data_size\fR field contains the length, in bytes, of the audio data
  67 segment. If this length is not known when the header is written, it should be
  68 set to \fBAUDIO_AU_UNKNOWN_SIZE\fR, defined as follows:
  69 .sp
  70 .in +2
  71 .nf
  72 AUDIO_AU_UNKNOWN_SIZE  ( ~0 )       /* (unsigned) -1 */
  73 .fi
  74 .in -2
  75
  76 .sp
  77 .LP
  78 When the \fBau_data_size\fR field contains \fBAUDIO_AU_UNKNOWN_SIZE\fR, the
  79 length of the audio data can be determined by subtracting \fBau_offset\fR from
  80 the total length of the file.
  81 .sp
  82 .LP
  83 The encoding field contains one of the following enumerated keys:
  84 .sp
  85 .in +2
  86 .nf
  87 AUDIO_AU_ENCODING_ULAW         /* 8-bit u-law */
  88 AUDIO_AU_ENCODING_LINEAR_8     /* 8-bit linear PCM */
  89 AUDIO_AU_ENCODING_LINEAR_16    /* 16-bit linear PCM */
  90 AUDIO_AU_ENCODING_LINEAR_24    /* 24-bit linear PCM */
  91 AUDIO_AU_ENCODING_LINEAR_32    /* 32-bit linear PCM */
  92 AUDIO_AU_ENCODING_FLOAT        /* Floating point */
  93 AUDIO_AU_ENCODING_DOUBLE       /* Double precision float */
  94 AUDIO_AU_ENCODING_FRAGMENTED   /* Fragmented sample data */
  95 AUDIO_AU_ENCODING_DSP          /* DSP program */
  96 AUDIO_AU_ENCODING_FIXED_8      /* 8-bit fixed point */
  97 AUDIO_AU_ENCODING_FIXED_16     /* 16-bit fixed point */
  98 AUDIO_AU_ENCODING_FIXED_24     /* 24-bit fixed point */
  99 AUDIO_AU_ENCODING_FIXED_32     /* 32-bit fixed point */
 100 AUDIO_AU_ENCODING_EMPHASIS     /* 16-bit linear with emphasis */
 101 AUDIO_AU_ENCODING_COMPRESSED   /* 16-bit linear compressed */
 102 AUDIO_AU_ENCODING_EMP_COMP     /* 16-bit linear with emphasis
 103                                               and compression */
 104 AUDIO_AU_ENCODING_MUSIC_KIT    /* Music kit DSP commands */
 105 AUDIO_AU_ENCODING_ADPCM_G721   /* CCITT G.721 ADPCM */
 106 AUDIO_AU_ENCODING_ADPCM_G722   /* CCITT G.722 ADPCM */
 107 AUDIO_AU_ENCODING_ADPCM_G723_3 /* CCITT G.723.3 ADPCM */
 108 AUDIO_AU_ENCODING_ADPCM_G723_5 /* CCITT G.723.5 ADPCM */
 109 AUDIO_AU_ENCODING_ALAW         /* 8-bit A-law G.711 */
 110 .fi
 111 .in -2
 112
 113 .sp
 114 .LP
 115 All of the linear encoding formats are signed integers centered at zero.
 116 .sp
 117 .LP
 118 The \fBau_sample_rate\fR field contains the audio file's sampling rate in
 119 samples per second. Some common sample rates include 8000, 11025, 22050, 44100,
 120 and 48000 samples per second.
 121 .sp
 122 .LP
 123 The \fBau_channels\fR field contains the number of interleaved data channels.
 124 For monaural data, this value is set to one. For stereo data, this value is set
 125 to two. More than two data channels can be interleaved, but such formats are
 126 currently unsupported by the Solaris audio driver architecture. For a stereo
 127 sound file, the first sample is the left track and the second sample is the
 128 right track.
 129 .sp
 130 .LP
 131 The optional info field is a variable length annotation field that can be
 132 either text or data. If it is a text description of the sound, then it should
 133 be NULL terminated. However, some older files might not be terminated properly.
 134 The size of the info field is set when the structure is created and cannot be
 135 enlarged later.
 136 .SS "Macros"
 137 .sp
 138 .LP
 139 Accessing all of the AU audio structure members should be done through the
 140 supplied \fBAUDIO_AU_FILE2HOST\fR and \fBAUDIO_AU_HOST2FILE\fR macros. By
 141 always using these macros, code will be byte-order independent. See the example
 142 below.
 143 .SH EXAMPLES
 144 .LP
 145 \fBExample 1 \fRDisplaying Header Information for a Sound File
 146 .sp
 147 .LP
 148 The following program reads and displays the header information for an AU sound
 149 file. The \fBAUDIO_AU_FILE2HOST\fR macro ensures that this information will
 150 always be in the proper byte order.
 151
 152 .sp
 153 .in +2
 154 .nf
 155 void main(void)
 156 {
 157      au_filehdr_t    hdr;
 158      au_filehdr_t    local;
 159      int             fd;
 160      char            *name = "bark.au";
 161
 162      if ((fd = open(name, O_RDONLY)) < 0) {
 163           printf("can't open file %s\en", name);
 164      exit(1);
 165      }
 166
 167      (void) read(fd, &hdr, sizeof (hdr));
 168
 169      AUDIO_AU_FILE2HOST(&hdr.au_magic, &local.au_magic);
 170      AUDIO_AU_FILE2HOST(&hdr.au_offset, &local.au_offset);
 171      AUDIO_AU_FILE2HOST(&hdr.au_data_size, &local.au_data_size);
 172      AUDIO_AU_FILE2HOST(&hdr.au_encoding, &local.au_encoding);
 173      AUDIO_AU_FILE2HOST(&hdr.au_sample_rate, &local.au_sample_rate);
 174      AUDIO_AU_FILE2HOST(&hdr.au_channels, &local.au_channels);
 175
 176      printf("Magic = %x\en", local.au_magic);
 177      printf("Offset = %d\en", local.au_offset);
 178      printf("Number of data bytes = %d\en", local.au_data_size);
 179      printf("Sound format = %d\en", local.au_encoding);
 180      printf("Sample rate = %d\en", local.au_sample_rate);
 181      printf("Number of channels = %d\en", local.au_channels);
 182
 183      (void) close(fd);
 184 }
 185 .fi
 186 .in -2
 187
 188 .SH ATTRIBUTES
 189 .sp
 190 .LP
 191 See \fBattributes\fR(5) for descriptions of the following attributes:
 192 .sp
 193
 194 .sp
 195 .TS
 196 box;
 197 c | c
 198 l | l .
 199 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 200 _
 201 Stability Level Evolving
 202 .TE
 203
 204 .SH SEE ALSO
 205 .sp
 206 .LP
 207 \fBattributes\fR(5)
 208 .SH NOTES
 209 .sp
 210 .LP
 211 Some older AU audio files are incorrectly coded with info strings that are not
 212 properly NULL-terminated. Thus, applications should always use the \fBau_offset
 213 value\fR to find the end of the info data and the beginning of the audio data.