DOCS/tech/realcodecs/audio-codecs.txt

   1 all audio codecs (cook,atrk,14_4,28_8,dnet,sipr) have the same interface,
   2 but i have only analyzed the cook codec
   3
   4
   5 audio properties (hex)
   6
   7 00 short text/description of the format (bitrate, when to use)
   8 01 bitrate (bits/s) //avg. bytes/sec output
   9 02 ulong: ?
  10    ulong: samples per second
  11    ushort: bits/sample
  12    ushort: number of channels
  13 03 same as 02 //constant 2
  14 04 long description
  15 05 constant 1 (always?)
  16 06 ulong: block align (input frame size for RADecode)
  17 07 string: minimum player version
  18 08 n/a
  19 09 n/a
  20 0A n/a
  21 0B n/a
  22 0C n/a
  23 0D ?
  24 0E ? leaf size
  25 0F ?
  26 10 ?
  27 11 ?
  28 12 ?
  29 13 min. output buffer size? max. number of samples?
  30 14 ?
  31
  32
  33
  34
  35 functions:
  36
  37 ulong result=RAOpenCodec2(ra_main_t *raMain);
  38
  39 ulong result=RAInitDecoder(ra_main_t *raMain, ra_init_struct *raInit);
  40 struct ra_init_struct {
  41         ulong sample_rate;
  42         ushort bits_per_sample; // unused by RAInitDecoder
  43         ushort number_of_channels;
  44         ushort unknown1;        // 0
  45         ushort unknown2;        // also unused (100)
  46         ulong leaf_size;        // leaf size (used for interleaving, but
  47                                 // exists in audio stream description header (ASDH))
  48         ulong block_align;      // packet size
  49         ulong bits_per_sample;  // unused (always 16)
  50         char *ext_data;         // 16 bytes located at the end of the
  51                                 // ASDH
  52 };
  53
  54 There are some information missing that you usually need for playback,
  55 like bits per sample (the fileds aren't read by RAInitDecoder()). These
  56 are hard coded in the "flavors", i.e. the sub formats. A flavor is an entry
  57 in the list of available format variations like bitrate, number of channels,
  58 decoding algorithm, and so on.We can get those information with the
  59 following command:
  60
  61
  62
  63 void *GetRAFlavorProperty(ra_main_t *raMain, ulong flavor, ulong property,
  64         short *property_length_in_bytes);
  65 returns property data for a specific data
  66
  67 This is not important, because it's just a read only function.
  68 These flavor properties don't seem to exist in
  69
  70
  71 ulong RADecode(ra_main_t *raMain, char *input_buffer,
  72         ulong input_buffer_size, char *output_buffer,
  73         ulong *decoded_bytes, ulong p6=-1);
  74
  75 RAFreeDecoder(ra_main_t *);
  76
  77 RACloseCodec(ra_main_t *);
  78
  79
  80 ulong RASetFlavor(ra_main_t *ra_main, ulong flavor);
  81
  82 Set the flavor of the stream.
  83
  84 a flavor is an entry in the list of available format variations like
  85 bitrate, number of channels, decoding algorithm, and so on
  86
  87
  88 audio data storage:
  89 -------------------
  90
  91 With Real Audio V5 (or earlier?), the audio streams can be interleaved,
  92 i.e. the stream is striped amongst several data packets. The packets
  93 (which have a fixed size packet_len) are split up into a fixed number
  94 of num_parts equally sized parts - I call them leaves in lack of
  95 better name. The leaves have the size leaf_size = packet_len / num_parts.
  96
  97 To create a bunch of packets, you need 2*num_parts stream packets.
  98 The first part of the first stream packet is stored in leaf number 0,
  99 the first part of the second into leaf number num_parts, the one of the
 100 next one into leaf number 1 etc. The following part of a stream packet
 101 is stored 2*num_packets behind the current part of the same stream packet.
 102
 103 In short words: when you have a matrix with the leaves as the values,
 104 it's a transposition in conjunction with a permutation.
 105
 106 packet | leaf          | stream packet, part no.
 107 -------+---------------+------------------------
 108 0      | 0             | (0,0)
 109 0      | 1             | (2,0)
 110 .      | .             | .
 111 .      | .             | .
 112 0      | num_parts-1   | (2*num_parts-2,0)
 113 0      | num_parts     | (1,0)
 114 0      | num_parts+1   | (3,0)
 115 .      | .             | .
 116 .      | .             | .
 117 0      | 2*num_parts-1 | (2*num_parts-1,0)
 118 1      | 0             | (0,1)
 119 .      | .             | .
 120 .      | .             | .
 121
 122
 123 sequence of calls:
 124 ------------------
 125
 126 RAOpenCodec2()
 127
 128 RAInitDecoder()
 129
 130 RASetFlavor()
 131
 132 RAGetFlavorProperty(0xE)
 133
 134 sequence of RADecode()s
 135
 136 once a RAGetFlavorProperty(0xE) after some RADecode()s
 137
 138 and occasionally the following sequence:
 139 RAGetFlavorProperty(0)
 140 RAGetFlavorProperty(7)
 141 which is rather pointless because they only return
 142 cleartext audio descriptions
 143
 144 RAFreeDecoder()
 145
 146 RACloseCodec()
 147
 148
 149
 150 RAFlush(ra_main_t *raMain, char *output_buffer, ulong *retval)
 151 will be called when seeking
 152 output_buffer points to the output buffer from the last
 153 decode operation.
 154 retval is unknown, returning always 0x18 in a specific sample
 155 -> further investigation needed