Rhapsody Data Structure ======================= File formats and version numbers -------------------------------- This document refers to files read and produced by Rhapsody up to and including 1.29 Note that Rhapsody version 1.00 produced files in format 0 Rhapsody versions 1.10 up to 1.29 produce files in format 1 and automatically convert format 0 files to format 1 immediately on loading. Versions 1.00 to 1.09 may be able to read, edit and play format 1 files but the consequences may be unpredictable and some information (eg concerning stave heights and midi port numbers) will be unavailable. The use of earlier versions of Rhapsody is therefore not recommended. The differences between format 0 and format 1 files are included in the specification which follows. The differences concern only the header slot and the stave data slots and an addition to the voice change slot. Rhapsody file specification --------------------------- A Rhapsody file consists of a number of 'slots' each of which has the following byte structure: number of bytes [1] &FF [1] slot_length (0-255) [n] (n = slot_length-2) Header slot ----------- The first slot is a header and has the following structure: format 0 files: [1] &FF [1] slot_length [1] number_of_staves [1] option_data (see 1.) [1] 0 [1] 0 (NB this byte was always 0 and is now the file format number) [1] 0 [n] title/composer (see 2.) [1] &0D format 1 files: [1] &FF [1] slot_length [1] number_of_staves [1] option_data (see 1.) [1] speed (see 1b.) [1] file format number (0 or 1) [1] offset to title/composer string (= 13) [1] MIDI beat channel (see 1c.) [1] MIDI beat pitch (see 1d.) [4] reserved (must be zero) [n] title/composer (see 2.) [1] &0D (Since 6 extra bytes of data have been introduced into format 1 files, early versions of Rhapsody will not read the title/composer string correctly. Moreover, since the offending bytes may contain control codes, unpredictable results will occur when the titles are printed.) Stave data slots ---------------- Then follows one slot for each stave: format 0 files: [1] &FF [1] slot_length [4] stave_data (see 3.) [n] stave_name (n = slot_length-7) [1] &0D format 1 files: [1] &FF [1] slot_length (=&22) [4] stave_data (see 3.) [4] stave_data2 (see 3b.) [12] CR terminated stave name string [12] CR terminated string containing the last 9 characters of an Archimedes voice name (Since several extra bytes of data have been introduced into format 1 files, early versions of Rhapsody will not read stave names correctly. Moreover, since the offending bytes may contain control codes, unpredictable results will occur when the stave names are printed.) Music data slots ---------------- The music data consists of any number of slots each of which have the following structure: [1] &FF [1] slot_length [1] slot_width (see 4.) [1] data code [n] data [1] data code [n] data etc. Slots whose slot_width is zero are ignored by version 1.00 One such slot is used by version 1.15+ and is used to store formatting information. It always follows the stave_data slots and precedes any music data. Its structure is as follows: [1] &FF [1] slot_length [1] 0 [1] 1 (code for formatting data) [1] formatting scale (&60 means 100%) [1] maximum line number [1] flags bit 0 0=portrait 1=landscape bit 1 0=compression off 1=compression on bit 2 0=print 4/4 1=print C bit 3 0=print 2/2 1=print C' bits 4-7 unused (must be zero) [1] top space (in mm) [1] bottom space (in mm) [1] left margin (in mm) [1] right margin (in mm) [n] number of bars in each line The lines are numbered from zero. It follows that the minimum slot length is equal to the maximum line number+12. Details of the music codes are listed below. Terminator slot --------------- The last slot in the file has the form: [1] &FF [1] &00 Data Codes ---------- Data codes are put in numerical order. Barlines come first as they are frequently scanned. Notes and rests come last. Each code is divided into two nibbles. The high order nibble is the actual code; the low order nibble is the length of the data code. NB. Later versions of Rhapsody may add extra bytes to these codes. Such modifications will not necessarily affect the file format number. Applications which wish to read Rhapsody files should therefore ignore unexpected data, but should always respect the low order nibble of the data code. Barline (2 bytes) 0 &02 1 0=normal bar, 1=first time bar, 2=second time bar Dynamics (3 bytes) 0 &13 1 stave (see note 9.) 2 0=silent,1=ppp,3=pp,5=p,7=mp,9=mf,11=f,13=ff,15=fff values 2, 4, 6 etc represent half increments and are represented by ppp', pp' etc. Master volume (3 bytes) 0 &23 1 target volume (0-127). The 'normal' volume is 100 giving some room for crescendo. 2 number of beats (0-255). This is the number of (crotchet) beats over which the crescendo or decrescendo is to take place. Master tempo (3 bytes) 0 &33 1 target tempo/2 (0-255). (ie the available tempo range is 0-510 in steps of 2). All tempos are in crotchets per minute 2 number of beats (0-255). This is the number of (crotchet) beats over which the tempo change is to take place. MIDI commands 0 &4n This code is ignored by Rhapsody V 1.00 to 1.29 Clef (3 bytes) 0 &53 1 stave (see note 9.) 2 0=treble, 1=alto, 2=vocal tenor, 3=instrumental tenor, 4=bass Key Signature (3 bytes) 0 &63 1 stave (see note 9.) 2 0=7 flats, .., 7=no flats or sharps, .., 14=seven sharps If bit 4 is set, then the key signature is naturalised ie 16=7 naturals (in 'flat' positions, .., 30=7 naturals (in 'sharp' positions) Time signature (4 bytes) 0 &74 1 stave (ignored by Rhapsody V 1.00 to 1.29) 2 number of beats in a bar 3 beat type: 8=quaver, 4=crotchet, 2=minim etc. Switches (2 bytes) 0 &82 1 bit 0 if set, pedal on 1 if set, pedal off 2 if set, pause 3-7 unused Other barlines (2 bytes) 0 &92 1 0=half barline, 1=double bar, 2=endbar 3=start repeat, 4=end repeat, 5=double repeat Trill definitions (15 bytes) 0 &AF 1-12 six 2-byte trill definitions (see note 5.) 13 percentage length of staccato note (default=50) 14 percentage length of marcato note (default=80) Text (n-4 bytes of text, max 11) 0 Bn 1 stave (see note 9.) If bit 7 is set, the text is auto-spaced 2 position on stave (16 = centre of stave) 3 text (terminated with &0D) &Cn Reserved for phrasing and other graphic marks &Dn General purpose (depends on code in third byte) code 1 channel voice change 0 &D5 (only found in format 0) 1 stave 2 1 3 ARC voice number (0-32) 4 MIDI channel number (0-15) 0 &DF (only found in formats>0) 1 stave 2 1 3 MIDI program number+1 (0-128) 0 = don't send 4 MIDI channel number+1 (0-16) 0 = don't change 5-15 CR terminated string containing last 9 characters of an Archimedes voice name 0 &D4 1 stave 2 2 3 bits 0-4 transpose interval (unsigned) bit 5 1=transpose up, 0=transpose down bit 6 1=print start symbol, 0=print end symbol bit 7 1=print symbol, 0=don't print (overrides bit 6) All other codes are ignored by Rhapsody V 1.00 to 1.29. Rest (4 bytes) 0 &E4 1 stave (see note 9.) 2 rest length (see note 6.) 3 position on stave (ignored by Rhapsody V 1.00 to 1.29) Note cluster (n-4 notes) 0 &Fn 1 stave (see note 9.) 2 note length (see note 6.) 3 note flags (see note 7.) 4- lowest note attributes ... highest note attributes (see note 8.) Notes ----- 1. Option data (1 byte) bits if set... 0 MIDI flag (play MIDI) 1 speaker flag (play speaker) 2 scroll flag (scroll window while playing) 3 beat flag (play beats while playing) 4 repeat (play all repeats) 5 speaker beat flag (play beat through speaker) 6 MIDI beat flag (play beat through MIDI) 7 unused (must be zero) 1b. Speed (1 byte) 100 = normal speed 1c. MIDI beat channel (1 byte) bits 0-3 MIDI beat channel (default value 9 (ie channel 10)) 4-7 unused 1d. MIDI beat pitch bits 0-7 pitch: 60 = middle C (default value 37) 2. Title/composer string This has the form <&FF><movement><&FF><composer><&0D> Note that this information is only printed on the first page of a formatted score and has no other significance. The title is printed in a box at the top, the movement above the first stave at the start of the piece and the composer above the first stave on the right. 3. Stave_data (4 bytes, LSB first) bits default 0-3 MIDI channel number - 1 (0-15) 0 4-7 number of ARC sound channels allocated (0-8) 2 8-14 transpose interval + 64 64 15 join flag (join stave to one above if set) 0 16-18 stereo position (0-6) 3 (0=full left, 3=centre, 6=full right) 19-24 not used (must be zero) 0 25 percussion flag (percussion stave if set) 0 26-27 loudness (0-3) 2 28-31 MIDI port number 0 (bits 19-24 were originally defined as the Archimedes voice number. This definition has been changed in format 1 files) (bits 28-31 were originally defined as stave height with a default of 0. The definition has been changed in format 1 files.) 3b. Stave_data2 (4 bytes, LSB first) bits default 0-7 MIDI program number+1 (0-128) 0 = don't send 0 8-15 stave height (in OS units/8) 24 (the MIDI program number is transmitted whenever the piece is played from the start.) 4. Slot_width (1 byte) Each slot has a width (in OS units) which must be a multiple of 8. It also has a space in front of the note (used for accidentals etc). Slots with a slot width of zero are ignored by Rhapsody version 1.00 to 1.14. Slots of this type are reserved for future expansion. One such slot is used by version 1.15+ to store formatting information. For details see above. bits 0-2 frontspace (in OS units/8) (max 7) 3-7 width (in OS units/8) (max 31) 5. Trill definitions (2 bytes, LSB first) byte 1 bit 0 if set, upper interval is tone, else semi-tone 1 if set, lower interval is tone, else semi-tone 2-3 0 = trill begins on middle note 1 = trill begins on upper note 2 = trill begins on lower note 4 if set, trill has a turn at the start 5 if set, trill has a turn at the end 6-7 0 = trill has no shakes (ie is a grace note or turn) 1 = trill has one shake 2 = trill has two shakes 3 = trill has continuous shakes byte 2 number of notes per crotchet (1-31) 6. Note/rest length (1 byte) bit 0-2 0 = hemi-demi-semi-quaver 1 = demi-semi-quaver 2 = semi-quaver 3 = quaver 4 = crotchet 5 = minim 6 = semi-breve 7 = breve 3-4 0 = no dots 1 = single dot 2 = double dot 3 = triple dot 5 if set, note is a triplet 6 if set, note is tied (not applicable to rests) 7 if set, note has a downstalk (not applicable to rests) 7. Note flags (1 byte) bit 0-2 0 = no trill 1-6 = trill 1-6 3 unused (must be zero) 4-5 0=normal, 1=staccato, 2=marcato, 3=accented 6 Force beam 7 Break beam 8. Note attributes (1 byte) bit 0-4 position on stave (0-31) 5-7 0 = no accidental 1 = sharp 2 = flat 3 = natural 4 = double sharp 5 = double flat 6 = natural sharp 7 = natural flat 9. Stave number (1 byte) Staves are numbered from 1. Stave number zero is reserved and is ignored by Rhapsody V 1.00 to 1.29 Bits 0-5 determine the actual stave number. Bit 6 This is used by Rhapsody V 1.00 to 1.29 as a flag to indicate that the tail of this note has already been printed. Rhapsody expects this bit to be zero and will reset it to zero. Bit 7 This is used by Rhapsody V 1.00 to 1.29 as a flag to indicate that this note is tied and has already been played. Rhapsody expects this bit to be zero and will reset it to zero. Configuration file ------------------ byte bit meaning range default 00 max no of staves 8-63 24 01 max no of systems in formatted score/10 10-250 10 (shown as Max lines/page) 02 max no of transcribed bars/100 10-250 10 03 default stave height 16-48 24 04 0 if set print 4/4 as common 1 1 if set print 2/2 as alla breve 1 05 display size (0=tiny, 4=huge) 0-4 2 06 0 if set MIDI on 0 1 if set speaker on 1 2 if set scroll on 0 3 if set beat on 0 4 if set repeats on 0 5 if set speaker beat on 0 6 if set MIDI beat on 0 07 MIDI beat channel minus 1 0-15 9 08 MIDI beat pitch 12-96 37 09 top space (in mm) 0-100 25 0A bottom space 0-100 25 0B left margin 0-100 13 0C right margin 0-100 13 0D format scale (96=100%) 48-144/16 96 0E 0 if set compression on 0 1 if set landscape on 0 2 if set midithru on 0 (c) J.O.Linton April 1991