API tools faq
paste
Advertisement
Guest User

Untitled

a guest
Jul 24th, 2020
86
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 14.73 KB | None | 0 0
raw download clone embed print report
  1.  
  2. The XM module format description for XM files version $0104.
  3.  
  4. By Mr.H of Triton in 1994.
  5.  
  6. - Be prepared! Are you sure you want to know? :-)
  7.  
  8. << A LOT of comments, corrections and notes added by Guru and
  9. Alfred of Sahara Surfers in 1995. All additions are included in
  10. double angle brackets << like this >> and everything outside
  11. them is left intact. Note the HUGE amount of errors in the
  12. original text. Triton: Perhaps you'd like to include THIS in the
  13. next FT2 release? :-)
  14.  
  15. Not copyrighted, released into public domain (at least the
  16. additions by us). Feel free to do what you wish. Credits please.
  17.  
  18. Remember - the added information is based on REAL XM files. >>
  19.  
  20. {{ It still has some mistakes. These mistakes are fixed in the double curly
  21. braces blocks. Some clarifications are also made. These things are also
  22. released into public domain, and are written by a different person.
  23.  
  24. The person writing the curly brace comments is writing a program to write XM
  25. files, rather than to read them. }}
  26.  
  27. ============================================================================
  28.  
  29.  
  30. ******************************
  31. * The XM file structure: *
  32. ******************************
  33.  
  34. {{ Numbers are small-endian. "Word" is 16-bits. "Dword" is 32-bits. }}
  35.  
  36. Offset Length Type
  37.  
  38. 0 17 (char) ID text: 'Extended module: '
  39. << Nope: 'Extended Module: ' >>
  40. 17 20 (char) Module name, padded with zeroes
  41. 37 1 (char) $1a {{ DOS end-of-file character }}
  42. 38 20 (char) Tracker name
  43. {{ The name of the program used to create it,
  44. normally Fasttracker. }}
  45. 58 2 (word) Version number, hi-byte major and low-byte minor
  46. The current format is version $0103
  47. << Nope, it's $0104. Format versions
  48. below $0104 have a LOT of differences.
  49. Check this field! >>
  50.  
  51. 60 4 (dword) Header size
  52. << Calculated FROM THIS OFFSET, not from
  53. the beginning of the file! >>
  54. +4 2 (word) Song length (in patten order table)
  55. +6 2 (word) Restart position
  56. +8 2 (word) Number of channels (2,4,6,8,10,...,32)
  57. +10 2 (word) Number of patterns (max 256)
  58. +12 2 (word) Number of instruments (max 128)
  59. +14 2 (word) Flags: bit 0: 0 = Amiga frequency table (see below);
  60. 1 = Linear frequency table
  61. +16 2 (word) Default tempo {{ a.k.a. speed }}
  62. +18 2 (word) Default BPM {{ a.k.a. tempo }}
  63. +20 256 (byte) Pattern order table
  64.  
  65. Patterns:
  66. ---------
  67.  
  68. ? 4 (dword) Pattern header length {{ normally nine }}
  69. +4 1 (byte) Packing type (always 0)
  70. +5 2 (word) Number of rows in pattern (1..256)
  71. +7 2 (word) Packed patterndata size
  72. << Note! This is zero if the pattern is
  73. completely empty and no pattern data
  74. follows! >>
  75.  
  76. ? ? Packed pattern data
  77.  
  78. Instruments:
  79. ------------
  80.  
  81. ? 4 (dword) Instrument size << header that is >>
  82. +4 22 (char) Instrument name
  83. +26 1 (byte) Instrument type (always 0)
  84. << This seems pretty random, don't
  85. assume it's zero >>
  86. +27 2 (word) Number of samples in instrument
  87.  
  88. If the number of samples > 0, then the this will follow:
  89.  
  90. ! +29 4 (dword) Sample header size
  91. ! +33 96 (byte) Sample number for all notes
  92. {{ Zero for first sample }}
  93. ! +129 48 (byte) Points for volume envelope
  94. ! +177 48 (byte) Points for panning envelope
  95. ! +225 1 (byte) Number of volume points
  96. ! +226 1 (byte) Number of panning points
  97. ! +227 1 (byte) Volume sustain point
  98. ! +228 1 (byte) Volume loop start point
  99. ! +229 1 (byte) Volume loop end point
  100. ! +230 1 (byte) Panning sustain point
  101. ! +231 1 (byte) Panning loop start point
  102. ! +232 1 (byte) Panning loop end point
  103. ! +233 1 (byte) Volume type: bit 0: On; 1: Sustain; 2: Loop
  104. ! +234 1 (byte) Panning type: bit 0: On; 1: Sustain; 2: Loop
  105. ! +235 1 (byte) Vibrato type
  106. ! +236 1 (byte) Vibrato sweep
  107. ! +237 1 (byte) Vibrato depth
  108. ! +238 1 (byte) Vibrato rate
  109. ! +239 2 (word) Volume fadeout
  110. ! +241 2 (word) Reserved
  111. << "Instrument Size" field tends to be more than the
  112. actual size of the structure documented here (it
  113. includes also the extended instrument sample header
  114. above). So remember to check it and skip the additional
  115. bytes before the first sample header >>
  116. !
  117. ! Sample headers:
  118. ! ---------------
  119. !
  120. ! ? 4 (dword) Sample length {{ in bytes }}
  121. ! +4 4 (dword) Sample loop start {{ in bytes }}
  122. ! +8 4 (dword) Sample loop length {{ in bytes }}
  123. ! +12 1 (byte) Volume
  124. ! +13 1 (byte) Finetune (signed byte -16..+15)
  125. {{ Actually, -128..+127, in 1/128 semitones. }}
  126. ! +14 1 (byte) Type: Bit 0-1: 0 = No loop, 1 = Forward loop,
  127. ! 2 = Ping-pong loop;
  128. ! {{bit}} 4: 16-bit sampledata
  129. ! +15 1 (byte) Panning (0-255)
  130. ! +16 1 (byte) Relative note number (signed byte)
  131. ! +17 1 (byte) Reserved
  132. ! +18 22 (char) Sample name
  133.  
  134. << Note! After the instrument header the file contains
  135. ALL sample headers for the instrument followed by the
  136. sample data for all samples >>
  137. !
  138. ! Sample data:
  139. ! ------------
  140. !
  141. ! ? ? Sample data (signed): The samples are stored
  142. ! as delta values. To convert to real data:
  143. !
  144. ! old=0;
  145. ! for i=1 to len
  146. ! new=sample[i]+old;
  147. ! sample[i]=new;
  148. ! old=new;
  149.  
  150.  
  151.  
  152. ***********************
  153. * Pattern format: *
  154. ***********************
  155.  
  156. The patterns are stored as ordinary MOD patterns, except that each
  157. note is stored as 5 bytes:
  158.  
  159. ? 1 (byte) Note (0-71, 0 = C-0)
  160. << Hah. Actually note numbers are 1-96,
  161. 97 being the key-off note (try to find
  162. that in the documentation!) >>
  163. +1 1 (byte) Instrument (0-128)
  164. << More like 1-128 >>
  165. +2 1 (byte) Volume column byte (see below)
  166. +3 1 (byte) Effect type
  167. +4 1 (byte) Effect parameter
  168.  
  169. A simle packing scheme is also adopted, so that the patterns not become
  170. TOO large: Since the MSB in the note value is never used, if is used for
  171. the compression. If the bit is set, then the other bits are interpreted
  172. as follows:
  173.  
  174. bit 0 set: Note follows
  175. 1 set: Instrument follows
  176. 2 set: Volume column byte follows
  177. 3 set: Effect follows {{ Effect type follows. }}
  178. 4 set: Guess what! {{ Effect parameter follows. }}
  179.  
  180. It is very simple, but far from optimal. If you want a better,
  181. you can always repack the patterns in your loader.
  182.  
  183. {{ If any data is omitted, it is zero. }}
  184.  
  185.  
  186. ******************************
  187. * Volumes and envelopes: *
  188. ******************************
  189.  
  190. The volume formula:
  191.  
  192. FinalVol=(FadeOutVol/65536)*(EnvelopeVol/64)*(GlobalVol/64)*(Vol/64)*Scale;
  193.  
  194. << The FadeOutVol is originally 65535 and is decremented by
  195. instrument.fadeout each tick after note is released >>
  196.  
  197. The panning formula:
  198.  
  199. FinalPan=Pan+(EnvelopePan-32)*(128-Abs(Pan-128))/32;
  200.  
  201. << Note that the panning envelope values range from 0-64, not
  202. -128 - +127 >>
  203.  
  204. Envelope:
  205. ---------
  206.  
  207. The envelopes are processed once per frame, instead of every frame where
  208. no new notes are read. This is also true for the instrument vibrato and
  209. the fadeout. Since I am so lazy and the tracker is rather self-explaining
  210. I am not going to write any more for the moment.
  211.  
  212. {{ X coordinates range 0 to 324. Y coordinates range 0 to 64. }}
  213.  
  214. << Anyone have ANY idea how instrument autovibrato works? >>
  215.  
  216. {{ Yes, I do.
  217. Type = 0 for sine, 1 for square, 2 for saw, 3 for others.
  218. Sweep = timer before vibrato (range 0 to 255)
  219. Depth = amount of pitch changed (range 0 to 15)
  220. Rate = speed of vibrato (range 0 to 63)
  221. }}
  222.  
  223.  
  224. ********************************
  225. * Periods and frequencies: *
  226. ********************************
  227.  
  228. PatternNote = 0..95 (0 = C-0, 95 = B-7)
  229. << Blah: Note = 1..96, 1 = C-0, 97 = key off >>
  230.  
  231. FineTune = -128..+127 (-128 = -1 halftone, +127 = +127/128 halftones)
  232. RelativeTone = -96..95 (0 => C-4 = C-4)
  233.  
  234. RealNote = PatternNote + RelativeTone; (0..118, 0 = C-0, 118 = A#9)
  235.  
  236. Linear frequence table:
  237. -----------------------
  238.  
  239. Period = 10*12*16*4 - Note*16*4 - FineTune/2;
  240. Frequency = 8363*2^((6*12*16*4 - Period) / (12*16*4));
  241.  
  242. Amiga frequence table:
  243. ----------------------
  244.  
  245. Period = (PeriodTab[(Note MOD 12)*8 + FineTune/16]*(1-Frac(FineTune/16)) +
  246. PeriodTab[(Note MOD 12)*8 + FineTune/16]*(Frac(FineTune/16)))
  247. *16/2^(Note DIV 12);
  248. (The period is interpolated for finer finetune values)
  249. Frequency = 8363*1712/Period;
  250.  
  251. << The interpolation code above doesn't work because of
  252. several reasons:
  253. 1. It does not interpolate (try adding 1 to the
  254. PeriodTab index in the second line)
  255. 2. It may go past the table beginning for negative
  256. finetune values
  257. Write your own interpolation routine instead - it's not that
  258. hard. >>
  259.  
  260. PeriodTab = Array[0..12*8-1] of Word = (
  261. 907,900,894,887,881,875,868,862,856,850,844,838,832,826,820,814,
  262. 808,802,796,791,785,779,774,768,762,757,752,746,741,736,730,725,
  263. 720,715,709,704,699,694,689,684,678,675,670,665,660,655,651,646,
  264. 640,636,632,628,623,619,614,610,604,601,597,592,588,584,580,575,
  265. 570,567,563,559,555,551,547,543,538,535,532,528,524,520,516,513,
  266. 508,505,502,498,494,491,487,484,480,477,474,470,467,463,460,457);
  267.  
  268. << Note! The period table is made for 1-based note numbers, so in
  269. practise it contains the period values for B-3 to G#4. Fun. >>
  270.  
  271.  
  272. *************************
  273. * Standard effects: *
  274. *************************
  275.  
  276. 0 Appregio << ;) >>
  277. 1 (*) Porta up
  278. 2 (*) Porta down
  279. 3 (*) Tone porta
  280. 4 (*) Vibrato
  281. 5 (*) Tone porta+Volume slide
  282. 6 (*) Vibrato+Volume slide
  283. 7 (*) Tremolo
  284. 8 Set panning
  285. 9 Sample offset
  286. A (*) Volume slide
  287. B Position jump
  288. C Set volume
  289. D Pattern break
  290. E1 (*) Fine porta up
  291. E2 (*) Fine porta down
  292. E3 Set gliss control
  293. E4 Set vibrato control
  294. E5 Set finetune
  295. E6 Set loop begin/loop
  296. E7 Set tremolo control
  297. E9 Retrig note
  298. EA (*) Fine volume slide up
  299. EB (*) Fine volume slide down
  300. EC Note cut
  301. ED Note delay
  302. EE Pattern delay
  303. F Set tempo/BPM
  304. G Set global volume
  305. H (*) Global volume slide
  306. K Key off << also note number 97 >>
  307. L Set envelope position
  308. P (*) Panning slide
  309. R (*) Multi retrig note
  310. T Tremor
  311. X1 (*) Extra fine porta up
  312. X2 (*) Extra fine porta down
  313.  
  314. (*) = If the command byte is zero, the last nonzero byte for the
  315. command should be used.
  316.  
  317. << The commands are reasonably Protracker compatible although
  318. not all PT "features" (some might call them replay routine bugs)
  319. are implemented. >>
  320.  
  321. *********************************
  322. * Effects in volume column: *
  323. *********************************
  324.  
  325. All effects in the volume column should work as the standard effects.
  326. The volume column is interpreted before the standard effects, so
  327. some standard effects may override volume column effects.
  328.  
  329. Value Meaning
  330.  
  331. 0 Do nothing
  332. $10-$50 Set volume Value-$10
  333. : : :
  334. : : :
  335. $60-$6f Volume slide down
  336. $70-$7f Volume slide up
  337. $80-$8f Fine volume slide down
  338. $90-$9f Fine volume slide up
  339. $a0-$af Set vibrato speed
  340. $b0-$bf Vibrato
  341. $c0-$cf Set panning
  342. $d0-$df Panning slide left
  343. $e0-$ef Panning slide right
  344. $f0-$ff Tone porta
  345.  
  346.  
  347. << And here goes one more section that this document really
  348. should have had:
  349.  
  350. ********************
  351. * General layout *
  352. ********************
  353.  
  354. The layout of a typical XM is like this:
  355.  
  356. XM header (up to and excluding header size field, now 60 bytes)
  357. Rest of the header (length including header size field)
  358. Pattern 0 header (length in header)
  359. Pattern 0 data (length in header)
  360. Pattern 1 header (length in header)
  361. Pattern 1 data (length in header)
  362. ... (* number of patterns)
  363. Instrument 0 header (length in size field is this and next one together)
  364. if (numSample > 0)
  365. Extra header
  366. Sample 0 header (size in instrument extra header)
  367. Sample 1 header (size in instrument extra header)
  368. ... (* number of samples in instrument)
  369. Sample 0 data (length in sample header)
  370. Sample 1 data (length in sample header)
  371. ... (* number of samples in instrument)
  372. Instrument 1 header (length in size field is this and next one together)
  373. ... (* number of instruments)
  374. >>
  375.  
  376.  
  377.  
  378. ============================================================================
  379.  
  380. This should be just about everything (I hope?). You will probably need
  381. some information about the MOD format and maybe about S3M.
  382.  
  383. Have fun!
  384. << And we sure had! >>
  385.  
  386. Fredrik Huss / Mr.H of Triton
  387.  
  388. << Jarno Paananen & Petteri Kangaslampi - Guru & Alfred / S2
  389.  
  390. If you have questions that you think we might be able to
  391. answer, have found out more mistakes in this document, or
  392. know how instrument autovibrato works, e-mail us at:
  393. Jarno: jpaana@kauhajoki.fi
  394. _or_
  395. Petteri: pekangas@sci.fi
  396. >>
  397.  
  398.  
  399.  
  400.  
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement
Public Pastes
Advertisement
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!