-
Notifications
You must be signed in to change notification settings - Fork 3
/
MODFIL10.TXT
1884 lines (1413 loc) · 83.5 KB
/
MODFIL10.TXT
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// For more info -> [email protected]
// Hello Thunder,
//
// ByteRaver / TNT / NO_ID aka Erland Van Olmen ([email protected])
// typing here. Your MODFIL10.TXT file was a *GREAT* help for me (my
// .MOD loader is now better than the one of FT2, CP 2.0 or Inertia
// Player! ;) still, while I was programming, I made some corrections and
// completed the text here and there. You might as well find it usefull,
// even if the original file was released quite some time ago...
// Anyway, each time you see "//", it's an annotation from me.
// BTW, I wrote a MOD player for the GUS as well as for the SoundBlaster
// PRO II (Interpolation & volume amplify are provided for better sound
// quality); the source code has been released through Hornet.
// (www.hornet.org, file tnt-mp??.zip, first file was tnt-mp10.zip) A DOC
// describing the principles of digital mixing is included.
// Source code of the player is Pascal, only the mixer is written in 386+
// Real mode assembler.
//
// Bye, sorry for my awful English, hope to hear from you.
//
// ByteRaver.
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
Public file MODFIL10.TXT - Version 1.0 - by Thunder
Introduction
_______________________________
What this file attempts to do is describe the MOD format in detail and
elaborate on the 'effects' that are possible. This is the first version
of this file, so if there are mistakes (and I expect at least a couple),
please let me know. This information was compiled from a variety of
sources, many of them anonymous, so I will thank them all, and they
hopefully know who they are. I would like to keep this file up to date.
It will be posted as 'MODFILxx.TXT' or 'MODFILxx.ZIP', where 'xx' is the
version number (MODFIL10.TXT being the first release).
I assume that you have some prior knowledge of some 'technical' terms,
including: sample, channel (or voice), frequency, logarithmic vs. linear
volume, byte, word, long integer, and hexadecimal format. It also
assumes that you know something about the machine that you are
programming on. If you do not know these things, this file will NOT
teach you them. Refer to other sources before going further.
I am a PC programmer, so I cannot elaborate on particular procedures,
routines, methodologies, or tricks that can be performed on other
architechtures. I have written routines for the Gravis UltraSound,
which is probably the easiest sound card (on the PC anyway) to write MOD
routines for.
I disclaim everything in this file. This information is for your use
personally, but I don't care if you give it to everyone else on the
planet. I would like the file to stay intact, and if you use the
information a 'hello' to me in your program's credits would be nice. If
the information is wrong or gives you problems or damages your equipment
or person, tough luck. I am not responsible for anything you DO with
this information.
If you have additions, corrections, clarification or questions about this
information or this file, you can send them to me through the internet to
'[email protected]' or '[email protected]'.
Here is an overview of what is in this file:
1 General
2 File Format
2.1 Song Name
2.2 Sample Information
2.3 Number of patterns in song
2.4 Song end jump position
2.5 Pattern table
2.6 File format tag
2.7 Patterns
2.8 Sample data
_______________________________________________________________________
1
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
3 Playing the files
3.1 Timing
3.2 Periods
3.3 Fine-Tuning
3.4 Effects
3.5 Other information
4 Period and Volume tables
1.0 General
___________________________________________
Files with the extension '.MOD' are sequenced music files. The file
format has it's roots in the Commodore Amiga computer (yes!). These
files use different digital 'samples' played at various frequencies to
create three octaves of 'notes' for that sample. In addition to
different 'notes', there are a large number of 'effects' which can be
done to produce variations on the different notes.
There are many variations on the MOD format. Since the format originated
on the Commodore Amiga computer, the files were geared towards a machine
with 4 voices. These days, with a GUS (Gravis UltraSound), you have 32
independent voices. If you are programming for a sound board or device
that has only 1 or 2 digital voices, you will have to mix together the 4
to 8 output channels into those voices. I will not go into this process
here, since I do not have experience with it (you don't need to mix on
the GUS). If someone would like to mail me a TEXT explaination of how to
do the mixing, I will include it in this file. I DO NOT WANT CODE --
learn how to write english.
The earliest versions of the MOD format used a maximum of 15 instruments
and had 4 channels. Through some modifications in format, a 'newer'
standard emerged, with a maximum of 31 instruments and up to 8 channels.
You can tell what format of file you are working with by a four-character
tag field. The programs that are used to play these files on the Amiga
are called 'Noisetracker', 'Soundtracker', and 'Protracker'.
// There is also a (well-known) program called 'StarTrekker'. See section
// 2.6 (format tag fields) for more info.
2.0 File Format
_______________________________
What follows is a description of a file broken down in a field-by-field
format. This is just a general description. Please see the following
subsections for a detailed description of what each field is and what it
means.
'Big-End Word' refers to the word format on the Amiga. A 2-byte integer
value is a word. On the Amiga, this value has the internal
representation HHLL, where HH means the high-order byte and LL means the
low-order byte. The Intel chips (inside PCs) use a LLHH format for their
words. This means that if you are writing routines for the PC, you have
to flip the high and low order bytes to retrieve meaningful values.
_______________________________________________________________________
2
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
Just to piss off all the C programmers, I'm going to start the file
offset at 1 instead of 0.
// ?! Something against C programmers ;-) ? (I'm both, but above all C...)
+-----------------(in bytes)
|
v
Offset Length Format Description
======== ======== ========= =============
1 20 Chars Title of the song. If the title is not a
full 20 chars in length, it will be null-
terminated.
21 22 Chars Sample 1 name. If the name is not a full
22 chars in length, it will be null
terminated.
43 2 Big-End Sample 1 length in 2-byte words. Multiply
Word this value by 2 to get the length of the
sample in bytes.
45 1 SNibble Sample 1 finetune.
46 1 Byte Sample 1 linear volume.
47 2 Big-End Sample 1 repeat offset in 2-byte words.
Word Multiply this value by 2 to get the position
in bytes.
49 2 Big-End Sample 1 repeat length in 2-byte words.
Word Multiply this value by 2 to get the length
in bytes.
51 30 Sample 2 information. Same format.
81 30 Sample 3 information Same format.
. There will either be 15 or 31 sample information blocks.
. See the format tag field below for a description of how
. to find out how many instruments there are. We'll go on
. the assumption that there are 31 instruments in the file.
921 30 Sample 31 information.
951 1 Byte Number of patterns in SONG as played. //hex location 3B6
952 1 Byte Song end jump position.
953 128 Bytes Pattern Table. These list up to 128
pattern numbers and the order they should
be played in.
1081 4 Chars File format tag. //hex location 438
1085 ... Pattern and Sample data. Please see pattern section and
sample section for more information.
// The old NST format contains only 15 samples (instead of 31). Further it
// doesn't contain a file format tag (id). So Pattern data offset is at
// 20+15*30+1+1+128.
// If the file looks like plain garbage, e.g. you can't find any valid
// sample-size value, sample-name string (should be alfanumeric), ID
// field, ... the file may be compressed with PowerPacker 2.0
// To check this, look for the FIRST 4 bytes of the file. If this "string"
// reads "PP20" the .MOD file is compressed with PowerPacker...
// Use pp20unp.exe to decompress the file (it's included with the source
// of my MOD Player, which you can get at:
// www.Hornet.org/music/programs/players/tnt-mpXX.zip
// (XX = version nr, 1st version = 10)
_______________________________________________________________________
3
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
2.1 Song Name
_______________________________
This data is pretty self-representative. This is a C 'string' that is
null-terminated (i.e. ASCII character 0 is put at the end of the text is
the text does not fill up the entire field). Some module writers use
this field and the instrument name fields to write 'hello' messages to
their friends or dedications instead of giving names to the song or it's
samples. I in no way discourage this.
// As sample names are usually used for messages, the song title field
// effectively holds the song title (in 99.9% of the cases ;-))
2.2 Sample Information
_______________________________
Based on the format tag field, there can be 15 or 31 sampled instruments
for the song. These days it is rare to run into an 'older' format song
with only 15 instruments. Please see the 'File format tag' field for
more information on how to determine how many samples there are in a
file.
The first field in a sample information block is the sample's name. As
was mentioned above, these names are frequently used by the composer to
say hello to his or her friends. Again, I in no way discourage this. If
the sample name begins with a '#' character (ASCII $23 (35)) then this is
assumed not to be an instrument name, and is probably a message.
The second field is the sample length in words. Once again, since this
is a 680x0 word, the bytes have the order HHLL, and you have to swap them
to use the word on PCs. The first 2 bytes of the sample are used by the
Amiga players for repeat information, and therefore are NOT part of the
playable data. Therefore, if this field is evaluated to a length of less
than 3 bytes, there is NO sample.
The third field is the sample's initial finetune value. The lower four
bits represent a signed nibble (-8..7). Each finetune step changes the
note 1/8th of a semitone. This is implemented by switching to a
different table of period-values for each finetune value. See section
3.2 for a discussion of fine-tuning.
The fourth field is the sample's playback volume. These are LINEAR
values that range from 0 to 64, with 64 being maximum volume. If you are
implementing a MOD player, remember to check if you need to use
logarithmic volumes. 'Decibel' is a logrithmical unit, which represents
how we feel sound intensity. The volume and decibel value table for
conversions is on the next page.
_______________________________________________________________________
4
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
Volume Decibel Value Volume Decibel Value
------------------------- ------------------------
64 0.0 32 -6.0
63 -0.1 31 -6.3
62 -0.3 30 -6.6
61 -0.4 29 -6.9
60 -0.6 28 -7.2
59 -0.7 27 -7.5
58 -0.9 26 -7.8
57 -1.0 25 -8.2
56 -1.2 24 -8.5
55 -1.3 23 -8.9
54 -1.5 22 -9.3
53 -1.6 21 -9.7
52 -1.8 20 -10.1
51 -2.0 19 -10.5
50 -2.1 18 -11.0
49 -2.3 17 -11.5
48 -2.5 16 -12.0
47 -2.7 15 -12.6
46 -2.9 14 -13.2
45 -3.1 13 -13.8
44 -3.3 12 -14.5
43 -3.5 11 -15.3
42 -3.7 10 -16.1
41 -3.9 9 -17.0
40 -4.1 8 -18.1
39 -4.3 7 -19.2
38 -4.5 6 -20.6
37 -4.8 5 -22.1
36 -5.0 4 -24.1
35 -5.2 3 -26.6
34 -5.5 2 -30.1
33 -5.8 1 -36.1
0 Minus infinity
The reason for the table starting at 0 dB as the convention from
taperecorders of having 0 dB as the optimal recording condition, and
displaying anything worse as a negative number. Please see section 4.0
for a complete linear volume format for Gravis' UltraSound.
The fifth field in the sample information block is the sample repeat
start offset. Once this sample has been played completely from beginning
to end, if the repeat length (next field) is greater than two bytes it
will loop back to this position in the sample and continue playing. Once
it has played for the repeat length, it continues to loop back to the
repeat start offset. This means the sample continues playing until it is
told to stop.
The last, or sixth field in the sample information is the repeat length.
A sample is only looped if this value is greater than 2 bytes. See the
preceeding paragraph for more information on looping.
_______________________________________________________________________
5
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
2.3 Number of patterns in song
_______________________________
This byte represents the number of patterns which are played in the entire
SONG. This is NOT the number of patterns in the FILE. The file may
contain (theoretically) up to 256 patterns, whereas the song is just a
selection of those patterns. If I have 30 patterns in my file, and I just
want to play patterns 6, 12, 3, 7, and 8 in that order, this byte will have
the value 5.
2.4 Song end jump position
_______________________________
Historically, this byte has been used for many purposes. Most commonly
in the newer format it has been used to signify if a song is to be
repeated indefinitely. Some game programs have background music which
never ends. If this byte is less than 127, then it specifies the
position in the pattern table to jump to when the last pattern has been
played. If this byte is greater than or equal to 127, the song ends.
2.5 Pattern table
_______________________________
This 128 byte block lists the order that patterns in the file should be
played in. Only the number of bytes specified by the number of patterns
in the song (see section 2.3) can be considered valid. If the song is to
play patterns 6, 0, 12, 11, 21, and 10 in that order, then the table will
have those 6 values as the first 6 bytes:
Pattern Table
Position ---> 0 1 2 3 4 5 6 ---------> 127
|---|---|---|---|---|---|---|---...---|---|
|006|000|012|011|021|010| ????????? |
|---|---|---|---|---|---|---|---...---|---|
One of the effects which is possible (see section 3.4) is a position
jump. The argument to this effect is where to jump to in the PATTERN
TABLE. This does NOT specify which PATTERN to jump to.
In a particular pattern there are 64 lines. These lines are played in
order from 0 to 63. When the end of a pattern is reached, playing
continues with the next pattern in the pattern table, unless the current
pattern is the last one. If the current pattern IS the last one, check
the song end jump position (see section 2.4) to see if the song loops to
a certain position in the pattern table. Another one of the effects
which is possible (see section 3.4) is a pattern break. If this effect
is encountered, playing immediately jumps to the first line of the next
pattern.
// The effect $D will always skip to the next pattern, but NOT always to
// the first line of the next pattern (in the table). See the description
// of the effect for more information.
_______________________________________________________________________
6
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
2.6 File format tag
_______________________________
This is the most controversial field in the file. This field has been
the most 'ravaged', with many people using it in non-standard ways for
their own purposes. There are a few standard tags which you can find
here which tell you DEFINITELY what file format the file is, but there
are many more non-standard tags. This makes the job of deciding what
format a MOD is a difficult one. I will attempt to describe the known
formats below. If you know of one I miss, please let me know.
'M.K.', 'FLT4',
'M!K!', '4CHN' : 4 channels, 31 instruments
'6CHN' : 6 channels, 31 instruments
'8CHN', 'OCTA' : 8 channels, 31 instruments
// Another annotion about these tag fields: here you got some other fields.
// If you don't want to support them in your player, you should at least de-
// tect them. All these MODs have of course 31 instruments.
// 'FLT4', 'FLT8': Startrekker 4/8 channel file. ('FLT6' doesn't exists)
// 'CD81' : Falcon 8 channel MODs
// '2CHN' : FastTracker 2 Channel MODs
// 'yyCH' where yy can be 10, 12, .. 30, 32: FastTracker yy Channel MODs
// 'yyCH' where yy can be 11, 13, 15: TakeTracker 11, 13, 15 channel MODs
// 'TDZx' where x can be 1, 2 or 3: TakeTracker 1, 2, 3 channel MODs
// 'xCHN' where x can be 5, 7 or 9: TakeTracker 5, 7, 9 channel MODs
//
// Thanks must go to Inertia for most of these extra tag fields.
//
// All these formats, except for the FLT8 format, are *EXACTLY* the same as
// the standard M.K. 4 channel format; the only difference is the size of
// one pattern. The size of one pattern is calculated w/ the following
// "formula":
// (Nr_Of_Channels shl 8)
//
// ( Nr_Of_Channels shl 8 <====> Nr_Of_Channels*4*64
// ^ ^^
// | ||
// Note length: 4 bytes -----+ ||
// Lines/patttern: 64 ---------++
// )
// The tag '4CHN' doesn't exists.
//
// Some extra information about the "FLT8" -type MOD's:
//
// These MOD's have 8 channels, still the format isn't the same as the
// other 8 channel formats ("OCTA", "CD81", "8CHN"): instead of storing
// ONE 8-track pattern, it stores TWO 4-track patterns per logical pattern.
// i.e. The first 4 channels of the first logical pattern are stored in
// the first physical 4-channel pattern (size 1kb) whereas channel 5 until
// channel 8 of the first logical pattern are stored as the SECOND physical
// 4-channel pattern. Got it? ;-).
// If you convert all the 4 channel patterns to 8 channel patterns, do not
// forget to divide each pattern nr by 2 in the pattern sequence table!
Other information that is found in this field can be assumed to be
somebody's attempt at protection, or some other information that was used
in the 'older' file format. If you can't find any of the above
information, it is best to assume that it's a 4 channel file. As for how
many instruments there are, check the bytes at location 471 in the file.
If there is text there (ASCII $20-$7E (32-126)), then you can probably
assume it's a 31-instrument file. Otherwise, it's an older 15 instrument
file.
// The method described above works lovely!
2.7 Patterns
_______________________________
There can be any number of patterns in the file. They are stored after
the file header and before the sample data. There are USUALLY less than
64, but the maximum is not limited - if the file tag is 'M!K!' there are
definitely more than 64 patterns.
// The nr of patterns is limited to 128 (from 0 to 127).
The patterns are stored sequentially (i.e. the first pattern is #0, the
second pattern is #1, etc.). An individual pattern is made up of 64
'lines', stored sequentially (i.e. line 0 to line 63). Each 'line' is
comprised of a note for each channel. Each 'note' is made up of 4 bytes,
so depending on the number of channels in the file, there are 16, 24, or
32 bytes per line.
// there are nr_channels*4 bytes per line. That is: minimum 4, max. 128
For a four-channel file there are (4 bytes * 4 channels * 64 lines) =1024
bytes of information per pattern. To find out the number of patterns in
a particular file, calculate the length of 'header' information and add
to it the lengths of all samples that are mentioned in the sample
information blocks. Subtract this number from the file's total size and
divide by the number just computed (1024) to get the number of patterns
in the file.
// The method described above is not the best method to find out how many
// patterns are stored in the MOD; it will fail if the MOD contains garbage
// at the end of the file. A much better method is to scan through the
// pattern sequence table to find the highest value. Be sure to scan ALL
// the values (128 of them) and to increment the highest pattern nr once,
// because the patterns are numbered from zero...
// e.g. if the highest pattern nr you could find in the table is 16, there
// are 16+1=17 patterns.
_______________________________________________________________________
7
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
As mentioned above, each note is stored as 4 bytes. The information held
by these bytes has format shown below. How you display the contents of
the 4 bytes in a player is up to you. There is NO standard way to do
this.
Byte 1 Byte 2 Byte 3 Byte 4
--------- --------- --------- ---------
7654-3210 7654-3210 7654-3210 7654-3210
wwww XXXX xxxxxxxxx yyyy ZZZZ zzzzzzzzz
wwwwyyyy ( 8 bits) : sample number
XXXXxxxxxxxx (12 bits) : sample 'period'
ZZZZzzzzzzzz (12 bits) : effect and argument
The sample number refers to a sample specified in the sample information
block. Please see sections 2.2 and 2.8 for more information on the
samples.
The sample 'period' corresponds to a delay value on an Amiga computer.
Note that on an Intel processor, you have to order these 12 bits as
'XXXX0000xxxxxxxx' to read the value as a word. Please see sections 3.2
// NO! You should use XXXXxxxxxxxx instead of XXXX0000xxxxxxxx
// (I came on it whilst programming my own player.)
and 3.3 for more information on how to use these values.
The effect is an effect number and an argument for the effect. Please
see section 3.4 for a discussion of the effects and how to implement
them.
2.8 Sample data
_______________________________
The sample data follows all of the patterns. After you have finished
reading the pattern data, there will be just enough data left in the file
for all of the instruments specified in the sample information section.
The samples are stored sequentially from sample 1 to sample 31. The
sample's data is in 8-bit two's compliment format, so if it needs to be
in another format for your sound device to play it, don't forget to
convert (UltraSound users: you don't need to convert the data when
downloading).
As was mentioned in section 2.2, the first 2 bytes of the sample are used
by the Amiga MOD players for repeat information, and therefore are NOT
part of the playable data. PC users do not have to do anything with
these two bytes.
// Hum, I got wrong results when I skipped these two bytes. When I treated
// them as sample data, everything went fine... Dunno why.
// So I suggest you don't care about it.
// (especially chiptunes sounded really wrong)
_______________________________________________________________________
8
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
3.0 Playing the files
_______________________________
Section 3 deals with playing MOD files. Specifically, it deals with
playing them on PC hardware - hopefully a Gravis UltraSound. The
Ultrasound is ideal for this and many other types of sound and song
processing, and is exceptionally easy to program. Gravis makes available
an SDK (Software Development Kit) which has both C, C++, and (by the end
of November) Borland Pascal versions. If you are programming a MOD
player for other hardware, you may still be able to use this information
for reference.
3.1 Timing
_______________________________
If lines are played sequentially, then how long should the player wait
between successive lines? On the Amiga, the amount of time a note spends
on a channel before the next note is started is calculated by using some
complex formulas based on the PAL color carrier frequency. I will not
try to bore you with the details of these calculations here, and if you
wan't them, email me.
A song can be played at a speed ranging from 1 to 127, where the speed
specifies how many 'ticks' before playing the next sample. A tick is
supposed to happen every .02 seconds, which gives 50 ticks per second.
At the start of a line all samples specified on that line are started,
samples playing are modified, speed is changed, etc. Some effects
require that changes be made to a sample playing on a channel during the
course of a line. For example, the retrigger effect re-starts a sample
at a certain tick within a line. If the song is playing at speed 6 and
the effect specifies a retrigger on the 4th tick:
Time Tick
0.00 1 - start all samples and effects
0.02 2
0.04 3
0.06 4 - retrigger sample here
0.08 5
0.10 6
------------
0.00 1 - start next line
.
.
Unless a speed is specified on the first line of the first pattern, the
song should start playing at speed 6. Please see section 3.4, effect $F,
for more information on changes in speed.
_______________________________________________________________________
9
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
3.2 Periods
_______________________________
MOD players use a technique called frequency shifting to produce
different 'notes' of the same sample. If I play a sample at 10 KHz, it
will sound one octave higher if I double the frequency to 20 KHz, and one
octave lower if I halve the frequency to 5 KHz. Since there are 12 notes
per octave on a keyboard (these are called half-steps), each frequency
corresponds to one twelfth root of two (~1.05946) times the frequency of
it's predecessor (to the left). Therefore, if the C-1 frequency (the
note of C in octave 1) is 4144 Hz then:
Note: C-1 C#1 D-1 ... C-2 ...
Freq: 4144 4390 4651 ... 8288 ...
The Amiga playing routines were written to run off different interrupts
for different Amiga computers, based on whether the machine was a PAL or
NTSC machine. The 'period' values are measures which are used in
calculating how much data to send to each of the 4 Amiga channels per
second (thereby specifying the frequency or pitch of the output).
For PC programmers, you don't have to worry about this that much. The
thing to remember is that a 'magic number' divided by twice the period
value will give the rate (frequency) to play the sample at. Here are the
magic numbers and the corresponding formulae. I don't know which number
is better to use - It doesn't make a huge difference.
PAL Value NTSC Value
=========== ============
7093789.2 7159090.5
SampleRate = -------------- SampleRate = --------------
Period * 2 Period * 2
// On a GUS, you need to divide the above calculated frequency by a cer-
// tain "frequency divisor". The value of this divisor depends on the
// number of channels you allocated on the GUS. Here you have the official
// divisors:
// freq_divisors[19] = (
// 44.100, frequency divisor using 14 active voices (or less)
// 41.160, frequency divisor using 15 active voices
// 38.587, frequency divisor using 16 active voices
// 36.317, frequency divisor using 17 active voices
// 34.300, frequency divisor using 18 active voices
// 32.494, frequency divisor using 19 active voices
// 30.870, frequency divisor using 20 active voices
// 29.400, frequency divisor using 21 active voices
// 28.063, frequency divisor using 22 active voices
// 26.843, frequency divisor using 23 active voices
// 25.725, frequency divisor using 24 active voices
// 24.696, frequency divisor using 25 active voices
// 23.746, frequency divisor using 26 active voices
// 22.866, frequency divisor using 27 active voices
// 22.050, frequency divisor using 28 active voices
// 21.289, frequency divisor using 29 active voices
// 20.580, frequency divisor using 30 active voices
// 19.916, frequency divisor using 31 active voices
// 19.293 frequency divisor using 32 active voices
// );
//
// If you multiply these values by 1000 (e.g. 44100 instead of 44.100),
// you get the mixing rate of the GUS. As you see, the quality drops badly
// using 32 active voices...
//
// (BTW: Don't try to allocate less than 14 voices.)
// Thus the frequency you should pass to the GUS is calculated as follows:
//
// gus_freq = (7093789.2 / (2 * period)) / freq_divisors[nr_of_voices-14];
To determine what frequency to play a sample at, look up the specified
period value in a table based on the finetune setting (see section 3.3
for more information on fine-tuning). If the period is 0, then the
previous period used on that channel is used.
As an example, let's look at the period table for finetune 0. The notes
that are possible in each octave are:
C C# D D# E F F# G G# A A# B
Octave 1: 856, 808, 762, 720, 678, 640, 604, 570, 538, 508, 480, 453
Octave 2: 428, 404, 381, 360, 339, 320, 302, 285, 269, 254, 240, 226
Octave 3: 214, 202, 190, 180, 170, 160, 151, 143, 135, 127, 120, 113
Octave 0:1712,1616,1525,1440,1357,1281,1209,1141,1077,1017, 961, 907
Octave 4: 107, 101, 95, 90, 85, 80, 76, 71, 67, 64, 60, 57
If I was requested to play a sample at period 302, I would scan through
the period table until I hit that value. At that point, I know that the
note is called 'F#2', F-sharp in octave 2. I calculate the playback
frequency by doing the calculations on the next page.
_______________________________________________________________________
10
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
PAL Value NTSC Value
=========== ============
7093789.2 7159090.5
----------- = 11745 Hz ----------- = 11853 Hz
302 * 2 302 * 2
There are normally only three octaves (1 to 3) used in playing songs.
Octaves 0 and 4 are NOT standard. Some songs may use the values though,
and it's nice if your player can handle them. Full period tables for all
finetunes are listed in section 4.
If you wish to sample sounds to include in MOD files, remember that the
data must be stored in 8-bit 2's complement format. There is NO standard
sample rate when creating the samples. Most often the samples are done
on the rate corresponding to period C-3 (around 16.5 KHz), and sometimes
drums are sampled at A-3 (around 28 KHz).
If sample number is specified on a channel (sample #0), then the last
// (SampleNr is not zero)
sample used on that channel will be remembered if new notes come along.
Only one sample may play on a channel at a time, so playing a new sample
will cancel an old one - even if there is no actual sample data for the
new sample (a 'silent' sample). However, if you are constructing a MOD
file of your own and you use a "silent" sample it is polite to set its
default volume to 0.
If you have some memory (around 2k or so) to spare, you could make up a
table of words indexed by period value. The value of the word at the
index of a period is the corresponding frequency that the sample should
be played at. This saves you from having to calculate the frequencies
over and over again. If you still don't get what I'm talking about here:
I have a array of words, one for each period from the lowest (around 50)
// Normal Maximum Period = 907
// Normal Minimum Period = 108
// Extended Maximum Period = 1814
// Extended Minimum Period = 54
//
// Extended: when using octaves 0 & 4
// See the V-E-R-Y end of this file for a complete list of Period values,
// EXTENDED octaves included.
//
// If you want VERY extended octaves, you'll have to use different
// formulas.
to the highest (around 1712). I precalculate the contents of this table
so that at index 302 (the period for note F#2), there is the value 11853,
the frequency to use to get the note F#2. Therefore, when my player runs
accross this value and needs to know what frequency to play the sample
at, I simply look up the value in the table directly - no calculations.
If you still don't get what I'm talking about, you're screwed.
3.3 Fine-Tuning
_______________________________
Fine-tuning is a minor adjustment on how an instrument sounds. This is
implemented by small changes in the period values. The finetune value
for a sample specifies the adjustment on the period values for that
instrument. A fine-tune can also be specified for a specific instrument
by an effect, at which point the value in the effect will override the
one in the sample information block.
_______________________________________________________________________
11
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
The value in the sample information block is a signed nibble (4 bits,
signed 2's complement). Therefore, the values that can be found have the
following corresponding finetunes:
Value: 0 1 2 3 4 5 6 7 8 9 A B C D E F
Finetune: 0 +1 +2 +3 +4 +5 +6 +7 -8 -7 -6 -5 -4 -3 -2 -1
Section 4.0 specifies period values for all finetunes for octaves 1 to 3.
You could use these values in creating your array of frequency words (see
the end of section 3.2).
3.4 Effects
_______________________________
As was mentioned in section 2.7, the 4 bytes for a note have the
following format:
Byte 1 Byte 2 Byte 3 Byte 4
--------- --------- --------- ---------
7654-3210 7654-3210 7654-3210 7654-3210
wwww XXXX xxxxxxxxx yyyy ZZZZ zzzzzzzzz
wwwwyyyy ( 8 bits) : sample number
XXXXxxxxxxxx (12 bits) : sample 'period'
ZZZZzzzzzzzz (12 bits) : effect and argument
Again, how you display this information in a player is up to you. I have
seen a zillion different formats. I have described what the sample
number and period refer to. Here, we will look at the effects that are
possible.
At this point in time, the Amiga Protracker MOD player (version 2.3A/
3.01) has 28 effects. Some of these effects are redundant or not
possible on some PC sound cards. I will describe the effects and how
they are implemented on the Amiga. PC programmers will have to adapt the
effects they wish to implement on their own. All numbers are stated in
hexadecimal.
For the discussion of the effects, we will look at the 'effect and
argument' part of the 4 bytes in the following way:
Bit number: $CBA987654321
Mentioned above as: ZZZZzzzzzzzz
We will use: ZZZZxxxxyyyy
There are two types of effects, standard and extended. All effects use
the ZZZZ portion to declare the effect number. Standard effects use the
xxxx and yyyy portions as one or two arguments, either as an 8-bit value
when taken together in the form xxxxyyyy or as 2 nibbles xxxx and yyyy.
Extended effects have the ZZZZ effect number $E. They use the xxxx
portion to declare the extended effect number and the only the yyyy
portion as an argument.
_______________________________________________________________________
12
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
Here are the possible standard effects:
-----------------------------------------------------------------------
# Effect name Uses Arguments as
-----------------------------------------------------------------------
0 Arpeggio xxxx yyyy
1 Slide Up xxxxyyyy
2 Slide Down xxxxyyyy
3 Tone Portamento xxxxyyyy
4 Vibrato xxxx yyyy
5 Tone Portamento + Volume Slide xxxx yyyy
6 Vibrato + Volume Slide xxxx yyyy
7 Tremolo xxxx yyyy
8 Set Panning Position xxxxyyyy
9 Set SampleOffset xxxxyyyy
A VolumeSlide xxxx yyyy
B Position Jump xxxxyyyy
C Set Volume xxxxyyyy
D Pattern Break xxxxyyyy
E *Extended Effects see below
F Set Speed xxxxyyyy
// The "SET SPEED" command is also used to set extended speed: BPM.
And here are the possible extended effects:
---------------------------------
# Effect name
---------------------------------
E0 Set Filter
E1 FineSlide Up
E2 FineSlide Down
E3 Glissando Control
E4 Set Vibrato Waveform
E5 Set FineTune
E6 Set/Jump to Loop
E7 Set Tremolo Waveform
E8 NOT USED
E9 Retrig Note
EA Fine VolumeSlide Up
EB Fine VolumeSlide Down
EC NoteCut
ED NoteDelay
EE PatternDelay
EF Invert Loop
A description of each effect and how it is implemented is given on the
following pages. Once again, all values are given in hexadecimal unless
otherwise stated.
_______________________________________________________________________
13
MODFIL10.TXT THUNDER ([email protected])
________________________________________________________________________
-----------------------------------------------------------------------
0: Arpeggio
-----------------------------------------------------------------------
If a note as an effect number of 0, it is only an arpeggio if there is at
least one non-zero argument. When there is at least one valid argument,
this effect means to play the note specified, then the note+xxxx half-
steps, then the note+yyyy half-steps, and then return to the original
note. These changes are evenly spaced within the time for a line to be
played at the current speed.
This effect is usually used to simulate chords (where a major chord is
the note+4 half steps and the note+7 half-steps). This does not work
very well on most samples. This can also be used to produce a heavy
vibrato. Here is an example of this effect:
Note C-3, xxxx=4, yyyy=7
this will attempt to produce a C-major chord. At the beginning of a line
the C-3 note is played, then at 1/3 of the way through the line the note