Debian Codegraph @

upstream/mageia-cauldron/man1/midistats.1

raw
1 .TH MIDISTATS 1 "26 November 2025"
2 .SH NAME
3 \fBmidistats\fP \- program to summarize the statistical properties of a midi file
4 .SH SYNOPSIS
5 This is a long manual because the program extracts many different parameters
6 from the midi file depending upon the options selected. This manual
7 attempts to describe these parameters and how they are computed.
8 These parameters are formatted in a way so they can be read by other
9 applications such midiexplorer.tcl, runstats.tcl, and numerous Python
10 scripts.
11
12 Many of the options were designed specifically for analyzing the
13 percussion track of the midi file. They are described in a separate
14 section below (Other options).
15
16
17 .SH DESCRIPTION
18 If you run midistats without any options other than the name of
19 the midi input file, it will produce a table of values described
20 here. Each line of output starts with the name of the variable or
21 variable array and the associated values.
22 .PP
23 ntrks indicates the number of tracks in the midi file.
24 .PP
25 ppqn the number of midi pulses per quarter note.
26 .PP
27 keysig the key signature, followed by a major/minor flag, the number
28 of sharps (positive) or flats (negative) in the key, and the beat number
29 where the key signature was found.
30 .PP
31 trk is followed by the track number for which the following information
32 applies.
33 .PP
34 program is followed by the channel number and the General Midi Program
35 number.
36 .PP
37 trkinfo is an array of 19 numbers which indicates the statistical properties
38 of the track of interest. The following data is given:
39 0 the channel number,
40 1 the first program assigned to this channel,
41 2 the number of notes for this channel counting any chords as one note,
42 3 the number of chord notes excluding the bass note,
43 4 the sum of the MIDI pitches for all the notes,
44 5 the sum of the note durations in MIDI pulse units,
45 6 the number of pitchbend messages,
46 7 the number of control parameter messages,
47 8 the number of pressure messages.
48 9 the number of distinct rhythm patterns for each channel
49 10 the number of pulses the channel was inactive
50 11 the minimum pitch value
51 12 the maximum pitch value
52 13 the minimum note length in pulses
53 14 the maximum note length in pulses
54 15 the number of gaps in the channel
55 16 the entropy of the pitch class histogram for that channel
56 17 the number of notes whose pitch were the same as the previous note
57 18 the number of notes whose pitch changed by less than 4 semitones
58 19 the number of notes whose pitch changed by 4 or more semitones
59 20 the average note velocity
60 21 the standard deviation of the note velocity
61
62 (In event of a chords the maximum pitches are compared.)
63 .PP
64 After processing all the individual tracks, the following information
65 applies to the entire midi file.
66 .PP
67 npulses is the length of the longest midi track in midi pulse units
68 .PP
69 tempocmds specifies the number of times the tempo is changed in this
70 file.
71 .PP
72 pitchbends specifies the total number of pitchbends in this file.
73 .PP
74 pitchbendin c n specifies the number of pitchbends n in channel c
75 .PP
76 progs is a list of all the midi programs addressed
77 .PP
78 progsact the amount of activity for each of the above midi programs.
79 The activity is the sum of the note durations in midi pulse units.
80 .PP
81 progcolor: is a 17 dimensional vector where each component maps into
82 a specific group of MIDI programs. Some of these groups are, keyboard
83 instruments, brass instruments, wind instruments, and etc. More information
84 can be found in the midiexplorer documentation.
85 .PP
86 drums is a list of all the percussion instruments (channel 9) that were
87 used.
88 .PP
89 drumhits indicates the number of notes for each of the above percussion
90 instruments.
91 .PP
92 pitches is a histogram for the 11 pitch classes (C, C#, D ...B)
93 that occur in the midi file.
94 .PP
95 key indicates the key of the music, the number of sharps (positive) or
96 flats (negative) in the key signature, and a measure of the confidence
97 in this key signature. The key was estimated from the above pitch histogram
98 by convolving with Craig Sapp's model. The peak of rmaj or rmin (below)
99 indicates the key. A correlation less than 0.4 indicates that the pitch
100 histogram does not follow the histogram of a major or minor scale.
101 (It may be the result of a mixture of two key signatures.)
102 .PP
103 rmaj the cross correlation coefficients with Craig Sapp's major key model
104 for each of the 11 keys (C, C#, D, ...,B).
105 .PP
106 rmaj the cross correlation coefficients with Craig Sapp's minor key model
107 for each of the 11 keys (C, C#, D, ...,B).
108 .PP
109 pitchact is a similar histogram but is weighted by the length of
110 the notes.
111 .PP
112 chanvol indicates the value of the control volume commands in the
113 midi file for each of the 16 channels. The maximum value is 127.
114 It scales the loudness of the notes (velocity) by its value.
115 .PP
116 chnact returns the amount of note activity in each channel.
117 .PP
118 trkact returns the number of notes in each track.
119 .PP
120 totalrhythmpatterns is the total number of bar rhythm patterns for
121 all channels except the percussion channel.
122 .PP
123 collisions. Midistats counts the bar rhythm patterns using a hashing
124 function. Presently collisions are ignored so occasionally two
125 distinct rhythm patterns are counted as one.
126 .PP
127 Midistats prints a number of arrays which may be useful in
128 determining where the music in the track is a melody line or
129 chordal rhythmic support. These arrays indicate the properties
130 for each of the 16 channels. (The percussion channel 9 contains
131 zeros.) In the case same channel occurs in several tracks, these
132 numbers are the totals for all track containing that channel.
133 Here is a description of these properties.
134 .PP
135 programs: channel to midi program mapping
136 .PP
137 cnotes: the total number of notes in each channel
138 .PP
139 nnotes: the number of notes in each channel not including
140 those playing in the same time interval.
141 .br
142 nzeros: the number of notes whose previous note was the same pitch
143 .br
144 nsteps: the number of notes whose pitch difference with the previous
145 note was less than 4 semitones.
146 .br
147 njumps: the number of notes whose pitch difference with the previous
148 note was 4 or more semitones.
149 .br
150 rpats: the number of rhythmpatterns for each channels. This is a
151 duplication of data printed previously.
152 .br
153 pavg: the average pitch of all the notes for each channel.
154 .br
155 spread: the percentage of the track that each channel is active.
156 .PP
157 If some of the channels appear in more than one track, then
158 some of the above values may be incorrect.
159 .PP
160 In addition the midistats may return other codes that describe
161 other characteristics. They include
162
163 unquantized - the note onsets are not quantized
164 .br
165 triplets - 3 notes played in the time of 2 notes are present
166 .br
167 qnotes - the rhythm is basically simple
168 .br
169 clean_quantization - the note onsets are quantized into 1/4, 1/8, 1/16 time units.
170 .br
171 dithered_quantization - small variations in the quantized note onsets.
172 .br
173 Lyrics - lyrics are present in the meta data
174 .br
175 programcmd - there may be multiple program changes in a midi channel
176
177
178
179 .SH Other options
180
181 It is recommended that you only select one of the options
182 described here as the program was not designed to handle a
183 multiple number of options.
184
185 .PP
186 If you run midistats with the -CSV option, it will return the
187 results in a form of comma separated values that can be loaded
188 into a Python panda dataframe. Each line refers to one of the
189 16 midi channels. The following Python 3 code illustrates
190 how you would load the midistats output into a dataframe.
191
192 .br
193 import pandas as pd
194 .br
195 import io
196 .br
197 import subprocess
198 .br
199 cmd = ("midistats", "-CSV" , inputmidifilepath)
200 .br
201 process = subprocess.Popen(cmd, stdout=subprocess.PIPE)
202 .br
203 csv = io.StringIO(process.stdout.read().decode())
204 .br
205 df = pd.read_csv(csv)
206
207 where inputmidifilepath is the path to the midi file that
208 you are using. (eg. 'clean_midi/Zero/Chi sei.mid')
209
210 .PP
211 The MIDI file devotes channel 9 to the percussion instruments
212 and over 60 percussion instruments are defined in the MIDI
213 standard. Though there is a lot of diversity in the percussion
214 track, for most MIDI files only the first 10 or so percussion
215 instruments are important in defining the character of the track. The
216 program Midiexplorer has various tools for exposing the percussion
217 channel which are described in the documentation. The goal
218 here is to find the essential characteristics of the percussion
219 track which distinguishes the MIDI files. This is attempted
220 in the program midistats. Here is a short description.
221
222
223 .br
224
225 A number of experimental tools for analyzing the percussion channel
226 (track) were introduced into midistats and are accessible through
227 the runtime arguments. When these tools are used in a script which
228 runs through a collection of midi files, you can build a database
229 of percussion descriptors.
230
231 .SH OPTIONS
232 .PP
233 -corestats
234 .br
235 outputs a line with 5 numbers separated by tabs. eg
236 .br
237 1 8 384 4057 375
238 .br
239 It returns the number of tracks, the number of channels, the
240 number of divisions per quarter note beat (ppqn),
241 the number of note onsets in the midi file, and the maximum
242 number of quarter note beats in midi file.
243
244
245 .PP
246 -pulseanalysis
247 .br
248 counts the number of note onsets as a function of its onset time
249 relative to a beat, grouping them into 12 intervals and returns
250 the result as a discrete probability density function. Generally,
251 the distribution consists of a couple of peaks corresponding
252 to quarter notes or eigth notes. If the distribution is flat,
253 it indicates that the times of the note occurrences have not been
254 quantized into beats and fractions. Here is a sample output.
255 .br
256 0.349,0.000,0.000,0.160,0.000,0.000,0.298,0.000,0.000,0.191,0.000,0.000
257
258 .PP
259 -panal
260 .br
261 Counts the number of note onsets for each percussion instrument. The first
262 number is the code (pitch) of the instrument, the second number is the
263 number of occurrences. eg.
264 .br
265 35 337 37 16 38 432 39 208 40 231 42 1088 46 384 49 42 54 1104 57 5 70 1040 85 16
266
267 .PP
268 -ppatfor n
269 .br
270 where n is the code number of the percussion instrument. Each beat
271 is represented by a 4 bit number where the position of the on-bit
272 indicates the time in the beat when the drum onset occurs. The bits
273 are ordered from left to right (higher order bits to lower order
274 bits). This is the order of bits that you would expect in a
275 time series.
276 Thus 0 indicates that there was no note onset in that beat, 1 indicates
277 a note onset at the end of the beat, 4 indicates a note onset
278 in the middle of the beat, and etc. The function returns a string
279 of numbers ranging from 0 to 7 indicating the presence of note onsets
280 for the selected percussion instrument for the sequence of beats
281 in the midi file. Here is a truncated sample of the output.
282 .br
283 11 71 c1 1 11 51 f1 c1 1 11 51 e1 1 11 d1 c1 31 1 1 1 21 b1 d1 d1 51
284 .br
285 51 51 51 51 41 71 c1 11 1 11 41 11 1 11 41 11 1 11 41 11 31 51 41 11
286
287 .PP
288 -ppat
289 .br
290 midistats attempts to find two percussion instruments in the midi file
291 which come closest to acting as the bass drum and snare drum.
292 If it is unsuccessful, it returns a message of its failue. Otherwise,
293 encodes the position of these drum onsets in a 8 bit byte for each
294 quarter note beat in the midi file. The lower (right) 4 bits encode the
295 bass drum and the higher (left) 4 bits encode the snare drum in the
296 same manner as described above for -ppatfor. The integers are printed
297 in hexadecimal.
298 .br
299 02 88 20 02 a0 08 80 02 82 08 80 02 82 08 80 02 82 08 80 02 82 08
300 .br
301 80 02 82 08 80 02 82 08 80 02 82 08 20 a0 0a 08 80 02 82 08 80 02
302
303 .PP
304 -ppathist
305 .br
306 computes and displays the histogram of the values that would appear
307 when running the -ppat. eg.
308 .br
309 bass 35 337
310 .br
311 snare 38 432
312 .br
313 1 (0.1) 64 32 (2.0) 8 33 (2.1) 136 144 (9.0) 8 145 (9.1) 136
314 .br
315 The bass percussion code, the number of onsets, and the snare
316 percussion code and the number of onsets are given in the
317 first two lines. In the next line the number of occurrences of
318 each value in the -ppat listing is given. The number in parentheses
319 splits the two 4-bit values with a period. Thus 33 = (2*16 + 1).
320
321 .PP
322 -pitchclass
323 .br
324 Returns the pitch class distribution for the entire midi file.
325
326 .PP
327 -nseqfor n
328 .br
329 Note sequence for channel n. This option produces a string of bytes
330 indicating the presence of a note in a time unit corresponding to
331 an eigth note. Thus each quarter note beat is represented by two
332 bytes. The pitch class is represented by the line number on the
333 staff, where 0 is C. Thus the notes on a scale are represented
334 by 7 numbers, and sharps and flats are ignored. The line number is
335 then converted to a bit position in the byte, so that the pitch
336 classes are represented by the numbers 1,2,4,8, and etc. A chord
337 of consisting of two note onsets would set two of the corresponding
338 bits. If we were to represent the full chromatic scale consisting
339 of 12 pitches, then we would require two-byte integers or
340 twice of much memory.
341 .br
342 Though the pitch resolution is not sufficient to distinguish
343 major or minor chords, it should be sufficient to be identify some
344 repeating patterns.
345 .PP
346 -nseq
347 .br
348 Same as above except it is applied to all channels except the
349 percussion channel.
350 .br
351 .PP
352 -nseqtokens
353 Returns the number of distinct sequence elements for each channel.
354 The channel number and number of distinct elements separated by
355 a comma is returned in a tab separated list for all active channels
356 except the percussion channel. Here is an example.
357 .br
358 2,3 3,4 4,11 5,6 6,3 7,3 8,6 9,3 11,2 12,1
359 .br
360
361 -ver (version number)
362
363
364 .SH AUTHOR
365 Seymour Shlien <[email protected]>
366
367
368