home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 February / PCWorld_2000-02_cd.bin / Software / Servis / FFE / SOUND.SWG / 0041_SBStudio PAC.pas < prev    next >
Encoding:
Pascal/Delphi Source File  |  1997-05-11  |  12.0 KB  |  328 lines
  1.  
  2.  
  3.  
  4.             SBStudio II
  5.             (C) 1991-94 Henning Hellström
  6.             All rights reserved
  7.  
  8.  
  9.             Program documentation
  10.  
  11.             The SBStudio file format
  12.  
  13.             ═══════════════════════════════════════════════════════
  14.  
  15.  
  16.  
  17.             »The basic idea»
  18.             ──────────────
  19.  
  20.             When I created SBStudio II, I also created the need for
  21.             a new file format to support the new features.
  22.  
  23.             The format I came up with has many advantages. It is
  24.             easy to make loaders and savers for it, it has few
  25.             limitations, it takes up less diskspace than most other
  26.             formats and it is very easy to upgrade.
  27.  
  28.             The greatest advantage is that the format is built up
  29.             of data blocks, each starting with a four byte text ID
  30.             and a doubleword saying the length of the block.
  31.             This makes it possible for loaders to skip data they
  32.             don't support.
  33.             This is also what makes the format so easy to upgrade.
  34.  
  35.  
  36.             This file will cover the new format in great detail,
  37.             and i hope it will become a new standard in music file
  38.             formats.
  39.  
  40.  
  41.  
  42.             »Some background information»
  43.             ───────────────────────────
  44.  
  45.             The new format actually consists of three file types;
  46.  
  47.             PACKAGES (.PAC), SONGS (.SON) and SOUNDS (.SOU).
  48.  
  49.             A PACKAGE is really a SONG file with the needed SOUND
  50.             files attached to it.
  51.  
  52.  
  53.             As mentioned before, the format is built up of data
  54.             blocks starting with a four byte identifier.
  55.             This identifier is followed by a doubleword saying the
  56.             length of the data block, *excluding* these first eight
  57.             bytes.
  58.  
  59.             This makes it easy to find and read wanted elements
  60.             from the file without doing heavy calculations.
  61.  
  62.             Let's say you want to find a data block called 'TEST':
  63.  
  64.  
  65.               1. Ignore the first 8 bytes, start at byte 9.
  66.               2. Read four bytes.
  67.               3. If these four bytes are 'TEST', go to step 7.
  68.               4. If these four bytes are 'END ', the file doesn't
  69.                  contain the wanted block. Terminate.
  70.               5. Read a doubleword and add it to the read pointer.
  71.               6. Go to step 2.
  72.               7. Process data.
  73.  
  74.  
  75.             Please note that the files always start with a file
  76.             identifier with a block length of <file length-8>,
  77.             and end with an 'END ' identifier with a block length
  78.             of zero.
  79.  
  80.             I think you get the picture now, let's get down to
  81.             business!
  82.  
  83.  
  84.  
  85.             »The file format»
  86.             ───────────────
  87.  
  88.             This current format version is v1.04.
  89.  
  90.             Here is a list of the identifiers you should expect to
  91.             find in a v1.04 file.
  92.  
  93.             'Block length' represents the doubleword immediately
  94.             following the block identifier.
  95.             'DWord' means long integer or 4 bytes.
  96.             'Word' means integer or 2 bytes.
  97.  
  98.  
  99.             Package
  100.             ───────
  101.  
  102.             Identifier      : 'PACG'
  103.             Location        : At the beginning of a PACKAGE.
  104.             Block length    : File size - 8.
  105.             Block structure : None.
  106.  
  107.             Identifier      : 'PAIN'
  108.             Location        : Usually after the 'PACG' block.
  109.             Block length    : Expect anything.
  110.             Block structure : Word  - Package version.
  111.                               Word  - SBStudio version that saved
  112.                                       the package.
  113.                                       Other savers should write 0
  114.                                       here.
  115.                               Word  - Number of sounds in package
  116.                                       (may be 0).
  117.  
  118.  
  119.             Song
  120.             ────
  121.  
  122.             Identifier      : 'SONG'
  123.             Location        : At the beginning of a SONG file or
  124.                               inside a PACKAGE, usually after the
  125.                               'PAIN' block.
  126.                               Represents the start of a song
  127.                               structure.
  128.             Block length    : File size - 8 if it's at the
  129.                               beginning of a SONG file, 0 if it's
  130.                               inside a PACKAGE file.
  131.             Block structure : None.
  132.  
  133.             Identifier      : 'SONA'
  134.             Location        : In a song structure.
  135.             Block length    : Expect anything.
  136.             Block structure : The name of the song.
  137.                               This block is not needed.
  138.  
  139.             Identifier      : 'SOOR'
  140.             Location        : In a song structure.
  141.             Block length    : Expect anything.
  142.             Block structure : Block length/2 words, saying the
  143.                               playback order of the song sheets.
  144.                               This block is not needed.
  145.  
  146.             Identifier      : 'SOIN'
  147.             Location        : In a song structure.
  148.             Block length    : Expect anything.
  149.             Block structure : Byte  - Base speed, usually 6.
  150.                               Byte  - Base BPM, usually 125.
  151.                               Word  - Number of sheets in song,
  152.                                       must be at least 1.
  153.                               Byte  - Number of channels used in
  154.                                       song. 4-16 channels is
  155.                                       normal for v1.04.
  156.                               Byte  - Number of lines in sheet.
  157.                                       Should always be 64.
  158.                               Byte  - Number of bytes per channel
  159.                                       cell. Should always be 5.
  160.                               Byte  - Sheet packing:
  161.                                         Bit 0 - 0 = Unpacked.
  162.                                                 1 = Packed.
  163.                               Byte * channels - Pan positions for
  164.                                                 each channel. Pan
  165.                                                 range is 0h-Fh.
  166.  
  167.             Identifier      : 'SOSH'
  168.             Location        : In a song structure.
  169.             Block length    : Expect anything.
  170.             Block structure : This block contains one sheet.
  171.                               Read the chapter 'The sheet format'
  172.                               later in this file for details on
  173.                               the sheet structure.
  174.  
  175.  
  176.             Sound
  177.             ─────
  178.  
  179.             Identifier      : 'SND '
  180.             Location        : At the beginning of a SOUND file or
  181.                               inside a PACKAGE, usually after the
  182.                               song structure.
  183.                               Represents the start of a sound
  184.                               structure, which contain one sound.
  185.             Block length    : File size - 8 if it's at the
  186.                               beginning of a SOUND file, 0 if it's
  187.                               inside a PACKAGE file.
  188.             Block structure : None.
  189.  
  190.             Identifier      : 'SNNA'
  191.             Location        : In a sound structure.
  192.             Block length    : Expect anything.
  193.             Block structure : The name of the sound.
  194.  
  195.             Identifier      : 'SNIN'
  196.             Location        : In a sound structure.
  197.             Block length    : Expect anything.
  198.             Block structure : Word  - Sound number, only used in
  199.                                       PACKAGE.
  200.                               Word  - Reserved.
  201.                               Byte  - Fine tuning.
  202.                               Word  - Sound volume, 0-16384.
  203.                               Word  - Sound type:
  204.                                         Bit 0 - 1=PCM/0=Other.
  205.                                         Bit 1 - 1=16bit/0=8bit.
  206.                                       Format version 1.04 only
  207.                                       supports PCM sounds.
  208.                               DWord - Sound loop start.
  209.                               DWord - Sound loop end.
  210.                               Byte  - Sound packing:
  211.                                         Bit 0 - 0 = Unpacked.
  212.                                                 1 = Packed.
  213.                                       Format version 1.04 only
  214.                                       supports unpacked sounds.
  215.  
  216.             Identifier      : 'SNDT'
  217.             Location        : In a sound structure.
  218.             Block length    : Sample length.
  219.             Block structure : This block contains one sampled
  220.                               sound.
  221.  
  222.  
  223.             All
  224.             ───
  225.  
  226.             Identifier      : 'END '
  227.             Location        : At the end of all PACKAGE, SONG and
  228.                               SOUND files.
  229.             Block length    : 0
  230.             Block structure : None.
  231.  
  232.  
  233.  
  234.             »The sheet format»
  235.             ────────────────
  236.  
  237.             The sheet is where the song notes are stored.
  238.  
  239.             SBStudio v2.05 limits the total number of different
  240.             sheets to 64, but a song structure may contain up to
  241.             65535 sheets.
  242.  
  243.  
  244.             The sheet consists of 5 bytes per channel, 64 times.
  245.  
  246.             NOTE:
  247.  
  248.               This MAY change in future versions, but let's say
  249.               it won't for now. Check the values in the 'SOIN'
  250.               block of the song structure to be sure.
  251.  
  252.  
  253.             The 5 bytes represent one note. This is the format:
  254.  
  255.               Byte 0 - Note number 1-48, 0 = No note.
  256.  
  257.                        1 = C-1, 2 = C#1, 3 = D-1 ... 48 = B-4.
  258.  
  259.               Byte 1 - Sound number 1-99, 0 = No change.
  260.  
  261.               Byte 2 - Volume 1-65, 0 = No change.
  262.  
  263.               Byte 3 - Command 00h-0Fh.
  264.  
  265.               Byte 4 - Command parameter 00h-FFh.
  266.  
  267.  
  268.             Read the documentation part 'Programming the sheet'
  269.             for details on what the different commands do.
  270.  
  271.             When writing a loader, keep in mind that support for
  272.             more octaves, sounds and commands may be added to
  273.             future versions of the format.
  274.  
  275.  
  276.  
  277.             »The packed sheet format»
  278.             ───────────────────────
  279.  
  280.             SBStudio v2.05 saves all sheets in a packed format.
  281.  
  282.             The packed format is very simple, but may sometimes
  283.             dramatically reduce the file size.
  284.  
  285.  
  286.             When loading a sheet, you should always assume it is
  287.             type 1 packed. This will make your loader compatible
  288.             with both type 0 and 1 sheets, and reduce the number
  289.             of instructions needed.
  290.  
  291.             Because more packing types may come in the future, you
  292.             should always check the 'sheet packing' byte in the
  293.             'SOIN' block to see what type of packing is used.
  294.  
  295.  
  296.             Here is the format description.
  297.  
  298.             In a type 1 packed sheet, byte 0 or 2 in the 5 byte
  299.             channel cell may contain a special byte. The special
  300.             bytes are:
  301.  
  302.                 Value    Meaning
  303.                 ──────────────────────────────────────────────
  304.                  0FDh    End of channel cell. Next byte is the
  305.                          first byte of the next channel cell.
  306.  
  307.                  0FEh    End of sheet row. Next byte is the
  308.                          first byte of the next row.
  309.  
  310.                  0FFh    End of sheet. You are finished!
  311.                 ──────────────────────────────────────────────
  312.  
  313.  
  314.  
  315.             »Last words»
  316.             ──────────
  317.  
  318.             This should be all you need to know to write your own
  319.             loader or saver for the new format. If you run into
  320.             problems, please drop me a message in the SBStudio
  321.             conference at the SoundServer MBBS in Oslo. Read the
  322.             doc part 'About SBStudio' for details. Good luck!
  323.  
  324.  
  325.  
  326.             ═══════════════════════════════════════════════════════
  327.  
  328.