= SV8 specification draft =

Nota : All fields, unless explicitely specified otherwise are read and written in Big-Endian order.

== File magic number ==

Magic number is on 32bits and is equal to 'MPCK' or 0x4D50434B[[BR]]

== File extension ==

The prefered file extension for musepack files is .mpc

== Packet formatting ==

All packets are formatted using Key / Size / Payload.[[BR]]
Keys are 16 bits long. It's equivalent to the packet ID or type.[[BR]]
Size is a variable-size field using the same values as [http://svn.mplayerhq.hu/mplayer/trunk/DOCS/tech/nut.txt?view=markup nut] :[[BR]]
{{{
bits, big-endian
0xxx xxxx                                           - value 0 to  2^7-2
1xxx xxxx  0xxx xxxx                                - value 0 to 2^14-2
1xxx xxxx  1xxx xxxx  0xxx xxxx                     - value 0 to 2^21-2
1xxx xxxx  1xxx xxxx  1xxx xxxx  0xxx xxxx          - value 0 to 2^28-2
...
}}}

Size defines the packet length in bytes, including the Key and Size fields. So the minimum length of a block is 3 bytes.[[BR]]
The payload is the actual packet data. Its size can be null.[[BR]]
All unused bits in a packet MUST be null.[[BR]]

|| '''Field''' || '''Size (bits)''' || '''Value''' ||
|| Key || 16 || "EX" ||
|| Size || n*8; 0 < n < 10 || 0x1A ||
|| Payload || Size * 8 || "example" ||


== Summary of reserved packet keys ==

Allowed chars in key are [A-Z] (65 <= value <= 90), so 676 keys are valid out of 65536 possible.

|| '''Packet Name''' || '''Key''' || '''Mandatory''' ||
|| Stream Header || SH || yes ||
|| Replaygain || RG || yes ||
|| Encoder Info || EI || no ||
|| Seek Table Offset || SO || no ||
|| Audio Packet || AP || yes ||
|| Seek Table || ST || no ||
|| Stream End || SE || yes ||

== Stream Header Packet ==

This packet key is "SH".[[BR]]
It contains the informations needed to decode the stream. This block is mandatory and must be written before the first audio packet.[[BR]]

|| '''Field''' || '''Size (bits)''' || '''Value''' || '''Comment''' ||
|| CRC || 32 ||  || CRC 32 of the block (this field excluded). 0 = invalid ||
|| Stream version || 8 || 8 || Bitstream version ||
|| Sample count || n*8; 0 < n < 10 ||  || Number of samples in the stream. 0 = unknown ||
|| Beginning silence || n*8; 0 < n < 10 ||  || Number of samples to skip at the beginning of the stream ||
|| End silence || n*8; 0 < n < 10 ||  || Number of samples to skip at the end of the stream ||
|| Sample frequency || 3 || 0..7 || See table below ||
|| Max used bands || 5 || 1..32 || Maximum number of bands used in the file ||
|| Channel count || 4 || 1..16 || Number of channels in the stream ||
|| MS used || 1 ||  || True if Mid Side Stereo is enabled ||
|| Audio block frames || 3 || 0..7 || Number of frames per audio packet (4^value^=(1..16384)) ||

Do we need to specify the channel position ? Is there standard positions / order of the channels ?

The SV8 stream allow only to start decoding on first packet frame, so cutting the stream require to cut on packet boundaries. Beginning / End silence fields provides more precise cutting possibilities.[[BR]]

Frequency table
|| '''Value''' || '''Frequency (Hz)''' ||
|| 0 || 44100 ||
|| 1 || 48000 ||
|| 2 || 37800 ||
|| 3 || 32000 ||

The CRC used is this one : [http://www.w3.org/TR/PNG/#D-CRCAppendix http://www.w3.org/TR/PNG/#D-CRCAppendix].

== Replaygain Packet == 

This packet key is "RG".[[BR]]
It contains the necessary data needed to apply replaygain on the current stream. This packet is mandatory and must be written before the first audio packet.[[BR]]

|| '''Field''' || '''Size (bits)''' || '''Value''' || '''Comment''' ||
|| ReplayGain version || 8 || 1 || The replay gain version ||
|| Title gain || 16 ||  || The loudness calculated for the title, ''and not the gain that the player must apply'' ||
|| Title peak || 16 ||  ||  ||
|| Album gain || 16 ||  || The loudness calculated for the album ||
|| Album peak || 16 ||  ||  ||

The replay gain values are stored in dB in Q8.8 format.[[BR]]
The 0 value means that this field has not been computed (no gain must be applied in this case.[[BR]]
exemples :[[BR]]
 * Replay gain finds that this title as a loudness of 78.56 dB, it will be encoded as 78.56 * 256 ~ 20111 = 0x4E8F
 * For 16 bits output (range [-32767 32768]), the max is 68813 (out of range). it will be encoded as 20 * log10(68813) * 256 ~ 24769 = 0x60C1
 * For float output (range [-1 1]), the max is 0.96. it will be encoded as 20 * log10(0.96 * 2^15^) * 256 ~ 23029 = 0x59F5 (for peak values it is suggested to round to nearest higher integer)

== Encoder Info Packet ==

This packet key is "EI".[[BR]]

|| '''Field''' || '''Size (bits)''' || '''Value''' || '''Comment''' ||
|| Profile || 7 || 0..15.875 || quality in 4.3 format ||
|| PNS tool || 1 || True if enabled ||  ||
|| Major || 8 || 1 || Major version ||
|| Minor || 8 || 17 || Minor version, even numbers for stable version, odd when unstable ||
|| Build || 8 || 3 || Build ||


== Seek Table Offset Packet ==

This packet key is "SO".[[BR]]
It contains an offset to the seek table packet.[[BR]]
This packet must be written before the first audio packet. This packet must be present if the "ST" packet is present and is written after the first audio packet.

|| '''Field''' || '''Size (bits)''' || '''Value''' || '''Comment''' ||
|| Offset || n*8; 0 < n < 10 ||  || Offset from this packet to the seek table packet ||


== Audio Packet ==

This packet key is "AP".[[BR]]
It contains audio frames. The first frame is a key frame.[[BR]]

|| '''Field''' || '''Size (bits)''' || '''Comment''' ||
|| Audio Frames || ? || n (or less if last packet) frames of audio as defined in SH packet ||


== Seek Table Packet ==

This packet key is "ST".[[BR]]

|| '''Field''' || '''Size (bits)''' || '''Value''' || '''Comment''' ||
|| Seek Count || n*8; 0 < n < 10 ||  || Number of seek elements in this table ||
|| Seek Distance || 4 || 0..15 || Distance between referenced blocks = 2^Value^ ||
|| Seek Data || ? ||  ||  ||

Format of seek data :[[BR]]

 * Reference offset for seeking is the musepack magic number
 * First 2 values are stored using the same code as the packet size code.
 * Next values are coded as :
{{{
code = value(n) - 2*value(n-1) + value(n-2)
code <<= 1;
if (code < 0)
  code = -code | 1;
}}}
code is sent as [http://en.wikipedia.org/wiki/Golomb_code golomb code] with M = 2^12^.


== Security Packet ==

Checksum (MD5, SHA1) or error correcting code (LDPC).[[BR]]
To be defined later. May be better to keep security features external only.


== Stream End Packet ==

This packet key is "SE".[[BR]]
Recommended packet size is 3 bytes.[[BR]]
This packet is mandatory and must be the last stream packet. Tags, if present, must be written after this packet.


== Streaming ==

This file format can be used for streaming. The "SH" block is (can?) used as synchronization marker. The decoder will scan for a "SH" block and check its CRC. Once the decoder is synchronized, it will start decoding. It's up to the streaming server to choose when to send "SH" block.[[BR]]
There is currently no way to send tags during playback. This must be changed (a tag packet ?).


== Tags ==

No packet must be written after the stream end packet to allow tagging by other applications.[[BR]]
Remarks about tagging? Incompatibilities?[[BR]]