Librairie OMKant 3.0

by Benoît Meudic

Librairie OMKant 3.0

Edited by Karim Haddad

Published Date: 2003/04/02 01:51:40

This manual can not be copied, in whole or part, without the written consent of IRCAM.

This manual was written by Benoît Meudic, and was produced under the editorial responsibility of Karim Haddad, Marketing and

Communication Dept. , IRCAM.

OpenMusic was conceived and programmed by Gérard Assayag and Carlos Agon.

The OMKant library was conceived and programmed by Benoît Meudic .

Apple Macintosh™ is a trademark of Apple Computer, Inc.

OpenMusic™ is a trademark of IRCAM.

Copyright © 2003 by IRCAM. All rights reserved.

The use of this software and its documentation is restricted to members of the IRCAM software users’ group. For any

supplementary information, contact:

Marketing and Communication Dept.,

IRCAM

1 place Igor-Stravinsky

F-75004,Paris

FRANCE

Phone:(33) (1) 44 78 49 62

Fax: (33) (1) 42 77 29 47

Email: palumbo@ircam.fr

Send comments or suggestions to the editor:

Karim Haddad

Marketing and Communication Dept.,

IRCAM

1 place Igor-Stravinsky

F-75004,Paris

FRANCE

Phone:(33) (1) 44 78 16 05

Email: haddad@ircam.fr

For more information:

http://www.forumnet.ircam.fr

Table of ContentsIntroduction .......................................................................................................................... i

1. General description of the library ..................................................................................1

Segmentation ...............................................................................................................1Tempo and Beat extraction ...........................................................................................1Measure extraction .......................................................................................................1Quantization .................................................................................................................2

2. The graphical interface of "Kant" ..................................................................................3

The main interface window...........................................................................................3Segmentations .....................................................................................................3Separations..........................................................................................................3The orange separations .......................................................................................3Switch mode ........................................................................................................4Other general functions........................................................................................4

The input/output slots of the editor ...............................................................................4

3. Details on segmentations ...............................................................................................7

4. Details on the beat detection algorithms ......................................................................9

5. Details on the measure detection algorithms ............................................................11

6. Details on the quantizing algorithms ..........................................................................13

7. Where to find more help and contacts ........................................................................15

Ircam documentation iii

iv Ircam documentation

IntroductionOMKant is a library for rhythmic analysis of MIDI files.

It offers different functions for:

• segmentation of the music sequence

• tempo and beat extraction

• meter extraction

• quantization

The different functions are detailed below.

A tutorial is also available in the Library folder.

In this documentation, all the sentences that describe actions that manipulate the libraryKant in OpenMusic are in italic.

Ircam documentation i

Introduction

ii Ircam documentation

Chapter 1. General description of the libraryAll of the operations that you can do with the kant library are linked to (rhythmical) music

analysis.

Most of the functions of the library can be called from the main interface window of the OMbox "kant".

Load the library, create a box "kant" and open it (double-click): you will see the main inter-face window of the library.

SegmentationA general concept that is shared between the different functions of the library is the con-

cept of segmentation. An analysing of a music sequence with the library "Kant" is always asegmentation (a cutting) of the sequence in different parts. For instance, it is possible to cutthe sequence in different beat units, or metric units, or anything you want.

In the editor "Kant", a segmentation is represented by vertical lines (called separations)that delimit the different parts of the segmented sequence. To add manually a vertical line,press "alt" while clicking with the mouse on the sequence.

What to do with a segmentation:

• you can use the segmentation as input for beat detection

• you can use the segmentation as input for meter detection

• you can import or export segmentations by using the input or output slot "lseg" of the box"kant"

Tempo and Beat extractionIt consists in finding the beats of the music sequence.

You can use several different algorithms for that:

• an automatic beat tracking algorithm

• an algorithm that induces the beat from a segmentation

• an algorithm that asks you for a beat value

To find a beat, use one of the functions of the menu "Quantify".

Once you have found a beat, you can choose a value for the measure. The default value is1/4. You can also visualize the quantized sequence in the rhythmical editor "poly".

If you use one function of the menu "Quantify", the menu "Measure" and the button "pre-view" appear in orange while a new segmentation (in the format "+"-quant") is created in thelist of segmentations at the top right of the editor. It means that the beat of the sequence isknown, and that you can choose a value for the measure (menu "Measure") or vizualise therhythmical sequence (button "preview").

Ircam documentation1

Chapter 1. General description of the library

Measure extractionIt consists in finding the value for the measure. You must already have specified a beat.

You can use several algorithms for that:

• an automatic measure tracking algorithm

• an algorithm that induces the measure from a segmentation

• an algorithm that asks you for a measure value

To find a measure, first make sure that you have used one of the functions for finding thebeat. The menu "Measure" must be in orange. Then, use one of the functions of the menu"Measure".

QuantizationOnce you activate one function of the menu "Quantify", the sequence can automatically

be quantized with default parameters.

However, you still can change the parameters or specify some constraints:

• you can choose between two quantizing algorithm that are "omquantify" and "quantz"(developped by Paul Nauert)

• you can choose to take the rests into account or not

• you can choose some parameters for "omquantify" that are "max", "forbid", "offset" and"precis":

• <max/> is the maximum subdivision of the beat (8 with beat=quarter means 32nd note)

• <forbid> is a list of forbidden subdivision of the beat

• <offset> is an offset expressed as a ratio of the beat

• <precis> is a float in (0.0 .. 1.0) smaller values mean ’simplicity’ while bigger valuesmean ’precision’

You should see the omquantify documentation for more details on those parameters.

For choosing the quantizing algorithm or specify if you want to take rests into account,press the button "param".

For changing the parameters of "omquantify", double-click on the name of your segmenta-tion in the top-right list (remember that you must already have choosen a beat, and thus thename must be in the format "+".-quant".

2 Ircam documentation

Chapter 2. The graphical interface of "Kant"

The main interface windowMost of the functions of the library can be called from the main interface window of the

OM box "kant".

Load the library, create a box "kant" and open it (double-click): you will see the main inter-face window of the library.

The interface is very similar to the "chord-seq" editor.

Segmentations

On the top right, there is a list of the segmentations that you have created (a segmentationappears with the default name "seg" when you open the window for the first time).

You can edit this list with functions of the menu "Edit": "New segmentation", Copy segmen-tation", Delete segmentation" and Save segmentation".

You can also double-click on one name of the list to change some parameters (name andcolor of the segmentation).

Below the menu edit are the menus for segmenting (menu "segment"), finding the beat(menu "Quantify"), finding the measure (menu "Measure") and visualizing the rhythmicalsequence (button "Preview").

Separations

Once you have selected a segmentation name (click on a name of the list of segmentationat the top right of the editor ), you can segment the sequence manually or with the menu"Segment". The segments are delimited with vertical blue lines (called separations).

Ircam documentation3

Chapter 2. The graphical interface of "Kant"

If the name of your segmentation is in the format "+"-quant" then you can not ma-nipulate the separations as described below (see chapter 5) .

You can move manually the separations with the mouse. You can also delete them (buttonß) or create them (press "alt"+ click).

When you create a separation, it appears at the position of your mouse. Depending on theapproximation value that you specify in the box "graphical approx" (at the bottom right of theeditor), the separation will automatically be positionned onto the nearest note of the mouseposition.

You can select all the separation lines by "double-click" on them.

You can stretch the separations: select them, press "ctrl" click and move your mouse onthe right or on the left.

The orange separations

The two orange separations that appear delimit the area of the music sequence on whichyou want to make the segmentation and also the area that you want to quantize. You canmove them with the mouse (you cannot delete them) or specify their positions with:

• "alt"+"ctrl"+"click with mouse" for the orange separation on the left

• "alt"+"shift"+"click with mouse" for the orange separation on the right

Switch mode

It is possible to switch from the Kant functions to the chord-seq functions (if you want toedit notes for instance).

To switch from Kant to chord-seq, press "m" or use the menu "Edit"-"Mode Kant" or "Edit"-"Mode chord-seq".

Note: Note that you can not switch mode if your current segmentation (the highlighted name inthe top right list of segmentations) is in the form "+"-quant". Indeed, once the beat has been found,you can not edit the notes anymore.

Other general functions

You can combine several different segmentations: press "shift" and click on differentnames of segmentations. All the separations of the different segmentations appear. Thereare three different modes for combining the segmentations: "union", "intersection" and"x-or".

To change the combining mode, choose "Mode for combination of segmentations" in themenu "Edit".

Union: adds all the separations.

Intersection: shows the separations that are in common.

x-or: shows the separations that are not in common.

4 Ircam documentation

Chapter 2. The graphical interface of "Kant"

The input/output slots of the editor

The input/output slots are the same than the ones of the "chord-seq" editor, except the twolast ones: "labstract" and "lseg".

Warning! In any case, if you evaluate the output of the "kant" editor, don"t forget to

close it (select it and press "b") if you don"t want to loose all of your segmenta-tions. !

The slot "labstract" contains the functions that you can create in OpenMusic for doing yourown segmentation methods (see end of chapter 3) .

The slot "lseg" contains the onsets values of the segmentations that you have created.

You can use "lseg" as input: you add to the box "kant" the values (list of numbers in mil-liseconds) of segmentations you have defined in Open-Music.

You can use "lseg" as output: you get the onsets of the segmentations that you have definedinside the box "Kant".

Ircam documentation 5

Chapter 2. The graphical interface of "Kant"

6 Ircam documentation

Chapter 3. Details on segmentations

Several automatic segmentation methods are proposed in "Kant" (in the menu "segment"of the editor window):

• The methods "inter-onset max " and "inter-onset min " segment the sequence accord-ing to the notes that have locally maximal or minimal inter-onset. An inter-onset is thetemporal distance between two successive onsets. An onset is the temporal position (inmilliseconds) of a note.

You can choose one parameter called ’smooth". It is an integer that reduces the irreg-ularities of the courb of inter-onsets. The higher it is, the higher is the correction of theirregularities. Default value is 1.

• The methods "pitch max " and "pitch min " segment the sequence according to the notesthat have locally maximal or minimal pitch (in midicents).

• The methods " dynamic max " and "dynamic min " segment the sequence according tothe notes that have locally maximal or minimal dynamic value.

• The method "chords " segments the sequence according to the position of the chords. Atolerance value "approx-in-ms" is defined for clusters of notes with very near onsets.

• The method "specify " segments the sequence according to the constraints that we spec-ify in a parameter window. For instance, it is possible to position the separations on thepitches whose value is 6000 midicents: select the button "pitches", the button "= V1" andinput the value 6000 in the box "=V1".

• The method "grid " regularly segments the sequence. You can define the period("period_in_◦ms") in milliseconds.

Ircam documentation 7

Chapter 3. Details on segmentations

• The method "propagate period " regularly segments the sequence, but positions the seg-ments on notes if possible depending on an approximative value. The period ("pulsation")is defined in milliseconds and the approximative value ("approx_0..1") is between 0 and 1.

• The method "auto-correlation " segments the sequence according to the computation ofa period value with an auto-correlation function.

• The method "beat-tracking " segments the sequence according to the computation of thebeat positions with an automatic beat-extraction algorithm (the same algorithm than theone proposed in the menu "Quantify"). Contrary to the algorithm proposed in the menu"Quantify", the sequence is not quantized, and thus errors of segmentation can be manu-ally corrected.

• The method "segmentation->beat " uses the same automatic beat-extraction algorithm asabove, but takes into account the segmentation specified in the dialog window for definingsalient rhythmical events that will guide the beat-extraction algorithm in its search for beatpositions.

You can also define your own segmentation method in OpenMusic:

1. Create a patch, abstract it (click on it, press b and click two times on the grey box).

2. Add one input and one output. The input is a chord-seq object, and the output is the listof the positions (in milliseconds) of the separations.

3. Inside the patch, create your own functions that extract the list of positions of the sepa-rations from the chord-seq.

Then, you can connect the patch to the input slot "labstract" of the box "kant". You can alsoconnect a list of abstract patches or a list of lists of one patch and his name (a string).

In the menu "Segmentation", the function "change level" proposes to create or erase multi-ples or sub-multiples of the separations that you have created. For instance, if you want onlyone on two of the separations, select "2" in the box "level". If you want to add a separationbetween all of the separations that you have created, select "-2" in the box "level". The box"position" determines the position of the first separation (in number of current separations).

8 Ircam documentation

Chapter 4. Details on the beat detectionalgorithms

Most of the functions related to beat detection are in the menu "Quantify".

Two different algorithms can be used for beat-tracking:

I. The first is based on the separations of a segmentation: it finds the pgcd (bigest commondivisor) of the periods between the successive separations

II. The second can either be independent from the segmentation or can rely on the sepa-rations (they are considered as positions of salient rhythmical events).

• "Automatic beat tracking" (II): This algorithm finds automatically several possible beat val-ues associated to a graph of tempo. The user can choose the beat he prefers among theproposed ones.

• "Automatic beat and measure tracking" (II): This algorithm finds automatically one beatand one measure value. The user doesn"t choose any parameter.

• "Separations correspond to ...measures" (I): This algorithm finds the pgcd (bigest commondivisor) of the periods between the successive separations that are considered in the resultas measure positions.

• "Separations correspond to ...some of the beat positions" (I): This algorithm finds thepgcd (bigest common divisor) of the periods between the successive separations that areconsidered in the result as beat positions.

• "Separations correspond to ...the exact beat positions" (I): All the periods between twosuccessive separations are considered as identical and correspond to the beat value.

• "Separations correspond to ...rhythmic accents" (II): This algorithm finds automaticallyseveral possible beat values associated to a graph of tempo. The algorithm relies on thepositions of the separations that are considered as salient rhythmical events. The user canchoose the beat he prefers among the proposed ones.

Once one of the above functions has been chosen, a new segmentation is created. Itsname is in the format "+...-quant". It means that the position of the separations cannot bechanged anymore. Each separation corresponds to a beat position. The segmentation hasa tempo value (it appears on the top left of the sequence).

The rhythmical sequence corresponding to this segmentation can be visualized (press thebutton "preview"). You can transform a beat into a measure position or inversly a measure

Ircam documentation 9

Chapter 4. Details on the beat detection algorithms

position into a beat (see section below). You can change the tempo of the segmentation:double-click on the name of the segmentation in the top right list and change the valuetempo.

10 Ircam documentation

Chapter 5. Details on the measure detectionalgorithms

The functions of this section can only be used if you have chosen a beat value (see chapter4).

Most of the functions related to measure detection are in the menu "Measure".

The rhythmical value of reference for the measure (denominator of the measure value, forinstance 4 for 3/4) can be changed by double-clicking on the name of the segmentation inthe top right list of segmentations and then modifying the default value "quarter note perminute". Note that this value is common to all the measures of the sequence.

The following functions can be used for determining the number of beats (small verticallines) between each measure position (big vertical lines):

• "Automatic measure tracking": This algorithm proposes a static number of beats that isautomatically computed.

• "Transform selected separations to ...measures": This algorithm transforms the separa-tions that you have selected into measure positions.

• "Transform selected separations to ...pulses": This algorithm transforms the separationsthat you have selected into beat positions.

• "Choose": You can manually choose the number of beats between each measure position.

The functions "Change level" and "Automatic search for higher level" should be used if thenumber of beats between each measure position are all the same. The functions determineor propose to choose multiples or sub-multiples of the current number of beats.

All of the other functions in the format "*...*" are segmentation functions. If you use oneof them, the current position of the measures will be changed in order to correspond to theposition of the separations of the segmentation.

Ircam documentation 11

Chapter 5. Details on the measure detection algorithms

12 Ircam documentation

Chapter 6. Details on the quantizingalgorithms

Once you have chosen a beat (see chapter 4) , you can use two different functions forquantizing the sequence:

• omquantify

• quantz (developped by Paul Nauert)

You can select the quantizing function you want through the window you obtain if you press"param". With this window, you can also specify if you want to take the rest into account inthe quantization or not.

Moreover, you can change the parameters of "omquantify" (double-click on the name ofyour segmentation in the top-right list):

<max/> is the maximum subdivision of the beat (8 with beat=quarter means 32nd note)<forbid> is a list of forbidden subdivision of the beat<offset> is an offset expressed as a ratio of the beat<precis> is a float in (0.0 .. 1.0) smaller values mean ’simplicity’ while bigger values mean ’precision’

You can also change the parameter "forbid" for each separation by selecting one or severalseparations corresponding to measure positions (press "shift" for several separations) andthen pressing "o" to open the parameter window.

You should see the omquantify documentation for more details on those parameters.

If you want to vizualize the rhythmical sequence, press "preview". This preview cannot beedited.

You can also get the rhythmical sequence from the left output slot of the box "kant" called"self". Connect it to a "poly" editor. For that, you must have selected a segmentation for whichyou have chosen a beat (see chapter 4) .

Ircam documentation 13

Chapter 6. Details on the quantizing algorithms

14 Ircam documentation

Chapter 7. Where to find more help andcontacts

You should use the tutorials that are in the folder Libworkspace of OpenMusic.

You can also find a help window in the kant editor: press the button "?".

Last, you can contact me (benoit meudic) through the OpenMusic list or at the adress<meudic@ircam.fr >.

Ircam documentation 15

Chapter 7. Where to find more help and contacts

16 Ircam documentation