forked from utz82/tiatune
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathreadme.txt
157 lines (118 loc) · 5.29 KB
/
readme.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
********************************************************************************
TIAtune v0.3.0
by utz 11'2017 * irrlichtproject.de
updated by Thomas Jentzsch and utz 01'2022
********************************************************************************
Updates
================================================================================
- Optimized waveform generation code. This increased the sample rate from 10.4
to 13.5 kHz.
- All TIA waveforms are supported.
- Optimized music data format to save space.
- Song tempo can be controlled now
- About 700 more bytes are free now for music.
- Optional simple visuals
ABOUT
================================================================================
TIAtune is a music driver for the Atari 2600 (VCS) console. Unlike other TIA
music drivers, it does not rely on the on the TIA's built-in frequency
dividers. That means that the detune usually associated with TIA music is absent
in TIAtune.
Features
========
- 16-bit frequency dividers (accurate pitch within <0.15% margin)
- sample rate: 13.5 KHz
- per-step tempo, 6-bit tempo resolution
- BPM (~2.5 BMP granularity).
Limitations
===========
- 100% CPU time used, cannot render graphics at the same time as playing music
- fairly large player (528 bytes with demo music, was 1147 bytes)
The TIAtune source is designed to be assembled with the ACME cross-assembler.
XM CONVERTER
================================================================================
You can use the provided music.xm template to compose music for TIAtune. To use
the converter, you must first install the ACME assembler, which is available at
https://sourceforge.net/projects/acme-crossass/. You should also have the Stella
emulator installed. Then simply run compile.cmd (Windows) or compile.sh
(*nix, Mac OS X) to convert, assemble, and run the result in Stella.
The following limitations apply:
- Any changes to instruments/samples are ignored.
- FX commands are ignored, except for Fxx (change tempo, xx < 0x20)
- The range of instruments is limited:
- instruments 1 and 2: C0..G#8
- instrument 3: C0..A5
- instruments 4, 5 and 6: C0..G#4
- instrument 7: C0..G#2
- instrument 8: C0..A1
Pattern length is also limited. The actual limit depends on the converted data
size. In the worst case, you will run out of bytes after 51 rows, but normally
you can get away with 64 and more rows. Generally it is a good idea to keep
patterns short, though. The converter optimizes pattern data, but not the
overall pattern structure. That means you can often save some bytes by breaking
down your patterns into smaller parts and removing redundancies.
Linux and Mac users will have to build the converter from source. Provided you
have Rust and Cargo installed, building the converter should be a simple matter
of running
cargo build --release
in the xm2tiatune directory and then moving the build from target/release to the
main directory.
MUSIC DATA FORMAT
================================================================================
Music data for TIAtune consists of a sequence, followed by one or more patterns.
The music data must be provided in a file named "music.asm", which is included
by the main file.
Sequence
========
The sequence contains a list of ids of pointers to patterns, in the order in
which they are to be played. The sequence list must be terminated with a 0-byte.
The sequence may at most contain 255 entries.
The pattern pointer are split into a hi-byte and a lo-byte part, labelled
"pattern_lookup_hi" and "pattern_lookup_lo", respectively. The pattern pointer
must be ordered like the pattern definitions. The lo-list must be terminated
with the lo-pointer to the byte after the last pattern. For the hi-pointer, two
pointers are encoded into one byte (see example below).
The most simple sequence would thus be:
sequence
!byte 1 ;index to pattern1
!byte 0 ;terminator
pattern_lookup_lo
!byte <pattern1
!byte <pattern2
!byte <pattern3
!byte <patternEnd ; terminator
pattern_lookup_hi
!byte (>pattern1>>4)&$f0
!byte ((pattern2>>8)&$f)|((>pattern3>>4)&$f0)
Patterns
========
Patterns contain the actual music data. They consist of one or more rows
(steps), which in turn consist of 1-5 data bytes. The function of the data bytes
is as follows:
byte bits function
1 0 if set, skip updating channel 1
1 if set, skip updating channel 2
0..5 tempo (step length)
2 0..2 waveform channel 1 (0..4)
3..6 volume channel 1
3 0..7 note channel 1
4 0..2 waveform channel 2 (0..4)
3..6 volume channel 2
5 0..7 note channel 2
If bit 0 of byte 1 is set, byte 2 and 3 are omitted. Likewise, if bit 1 of byte
1 is set, byte 4 and 5 are omitted. On the first step of the first pattern in
the sequence, no data bytes may be omitted.
AUDCx equivalents of the waveform parameter, and their note ranges are as
follows:
wave AUDCx range
0 4,5,C,D C0..G#8
1 8 C0..G#8
2 1 C0..A5
3 6,A C0..G#4
4 7,9 C0..G#4
5 3 C0..G#2
6 2 C0..A1
Each pattern may contain up to 255 data bytes. Thus, each pattern may contain at
least 51 steps. In most cases however, it is advisable to use shorter patterns,
to optimize overall data usage.
For more information, check the provided example music.asm file.