Ajout de commentaires.
[minwii.git] / src / mxmMidi / DataTypeConverters.py
1 # -*- coding: ISO-8859-1 -*-
2
3 from struct import pack, unpack
4
5 """
6 This module contains functions for reading and writing the special data types
7 that a midi file contains.
8 """
9
10 """
11 nibbles are four bits. A byte consists of two nibles.
12 hiBits==0xF0, loBits==0x0F Especially used for setting
13 channel and event in 1. byte of musical midi events
14 """
15
16
17
18 def getNibbles(byte):
19 """
20 Returns hi and lo bits in a byte as a tuple
21 >>> getNibbles(142)
22 (8, 14)
23
24 Asserts byte value in byte range
25 >>> getNibbles(256)
26 Traceback (most recent call last):
27 ...
28 ValueError: Byte value out of range 0-255: 256
29 """
30 if not 0 <= byte <= 255:
31 raise ValueError('Byte value out of range 0-255: %s' % byte)
32 return (byte >> 4 & 0xF, byte & 0xF)
33
34
35 def setNibbles(hiNibble, loNibble):
36 """
37 Returns byte with value set according to hi and lo bits
38 Asserts hiNibble and loNibble in range(16)
39 >>> setNibbles(8, 14)
40 142
41
42 >>> setNibbles(8, 16)
43 Traceback (most recent call last):
44 ...
45 ValueError: Nible value out of range 0-15: (8, 16)
46 """
47 if not (0 <= hiNibble <= 15) or not (0 <= loNibble <= 15):
48 raise ValueError('Nible value out of range 0-15: (%s, %s)' % (hiNibble, loNibble))
49 return (hiNibble << 4) + loNibble
50
51
52
53 def readBew(value):
54 """
55 Reads string as big endian word, (asserts len(value) in [1,2,4])
56 >>> readBew('aáâã')
57 1642193635L
58 >>> readBew('aá')
59 25057
60 """
61 return unpack('>%s' % {1:'B', 2:'H', 4:'L'}[len(value)], value)[0]
62
63
64 def writeBew(value, length):
65 """
66 Write int as big endian formatted string, (asserts length in [1,2,4])
67 Difficult to print the result in doctest, so I do a simple roundabout test.
68 >>> readBew(writeBew(25057, 2))
69 25057
70 >>> readBew(writeBew(1642193635L, 4))
71 1642193635L
72 """
73 return pack('>%s' % {1:'B', 2:'H', 4:'L'}[length], value)
74
75
76
77 """
78 Variable Length Data (varlen) is a data format sprayed liberally throughout
79 a midi file. It can be anywhere from 1 to 4 bytes long.
80 If the 8'th bit is set in a byte another byte follows. The value is stored
81 in the lowest 7 bits of each byte. So max value is 4x7 bits = 28 bits.
82 """
83
84
85 def readVar(value):
86 """
87 Converts varlength format to integer. Just pass it 0 or more chars that
88 might be a varlen and it will only use the relevant chars.
89 use varLen(readVar(value)) to see how many bytes the integer value takes.
90 asserts len(value) >= 0
91 >>> readVar('\80@')
92 64
93 >>> readVar('áâãa')
94 205042145
95 """
96 sum = 0
97 for byte in unpack('%sB' % len(value), value):
98 sum = (sum << 7) + (byte & 0x7F)
99 if not 0x80 & byte: break # stop after last byte
100 return sum
101
102
103
104 def varLen(value):
105 """
106 Returns the the number of bytes an integer will be when
107 converted to varlength
108 """
109 if value <= 127:
110 return 1
111 elif value <= 16383:
112 return 2
113 elif value <= 2097151:
114 return 3
115 else:
116 return 4
117
118
119 def writeVar(value):
120 "Converts an integer to varlength format"
121 sevens = to_n_bits(value, varLen(value))
122 for i in range(len(sevens)-1):
123 sevens[i] = sevens[i] | 0x80
124 return fromBytes(sevens)
125
126
127 def to_n_bits(value, length=1, nbits=7):
128 "returns the integer value as a sequence of nbits bytes"
129 bytes = [(value >> (i*nbits)) & 0x7F for i in range(length)]
130 bytes.reverse()
131 return bytes
132
133
134 def toBytes(value):
135 "Turns a string into a list of byte values"
136 return unpack('%sB' % len(value), value)
137
138
139 def fromBytes(value):
140 "Turns a list of bytes into a string"
141 if not value:
142 return ''
143 return pack('%sB' % len(value), *value)
144
145
146
147 if __name__ == '__main__':
148
149 # print to7bits(0, 3)
150 # print to7bits(127, 3)
151 # print to7bits(255, 3)
152 # print to7bits(65536, 3)
153
154 # simple test cases
155
156 # print 'getHiLoHex', getNibbles(16)
157 # print 'setHiLoHex', setNibbles(1,0)
158 #
159 # print 'readBew', readBew('aáâã')
160 # print 'writeBew', writeBew(1642193635, 4)
161 #
162 # print 'varLen', varLen(1)
163 #
164 print 'readVar', readVar('\80@')
165 print 'writeVar', writeVar(8192)
166
167 print 'readVar', readVar('áâãa')
168 print 'writeVar', writeVar(205058401)
169 #
170 # vartest = '\x82\xF7\x80\x00'
171 # print 'toBytes', toBytes(vartest)
172 # print 'fromBytes', fromBytes([48, 49, 50,])
173
174
175 # instr = '\xFF\xFF\xFF\x00'
176 # print 'readVar', readVar(instr)
177 # inst2 = 268435455
178 # print inst2
179 # print writeVar(inst2)
180 # print writeVar(readVar(instr))
181
182 s1 = 0x00000000
183 print '%08X -' % s1, '00', writeVar(s1)
184 s2 = 0x00000040
185 print '%08X -' % s2, '40', writeVar(s2)
186 s3 = 0x0000007F
187 print '%08X -' % s3, '7F', writeVar(s3)
188 s4 = 0x00000080
189 print '%08X -' % s4, '81 00', writeVar(s4)
190 s5 = 0x00002000
191 print '%08X -' % s5, 'C0 00', writeVar(s5)
192 s6 = 0x00003FFF
193 print '%08X -' % s6, 'FF 7F', writeVar(s6)
194 s7 = 0x00004000
195 print '%08X -' % s7, '81 80 00', writeVar(s7)
196 s8 = 0x00100000
197 print '%08X -' % s8, 'C0 80 00', writeVar(s8)
198 s9 = 0x001FFFFF
199 print '%08X -' % s9, 'FF FF 7F', writeVar(s9)
200 s10 = 0x00200000
201 print '%08X -' % s10, '81 80 80 00', writeVar(s10)
202 s11 = 0x08000000
203 print '%08X -' % s11, 'C0 80 80 00', writeVar(s11)
204 s12 = 0x0FFFFFFF
205 print '%08X -' % s12, 'FF FF FF 7F', writeVar(s12)
206
207
208
209
210
211
212
213
214
215
216
217