v.0.9.7 (beta)
quince
user guide
english
developer guide
english
Thank you very much for your interest in quince ! quince is an open source software project initiated by Maximilian Marcoll in 2010. It is released under the GNU General Public License. You should have received a copy of the GNU General Public License along with quince. If not, see http://www.gnu.org/licenses/. quince can be downloaded from the quince website at: http://quince.maximilianmarcoll.de. The sources are available at http://github.com/mmax/quince. The quince icon was designed by Stephane Leonard. If you come across any errors in the documentation, bugs in the software itsself, if you need a plug-in for quince that you can't develop yourself, or if you have any other questions, please write to quince@maximilianmarcoll.de. Thank you!
Index
quince is a program for editing time based data on the mac. Although quince was developed to serve musical purposes, theoretically, not only audio but video and every other time based data type can be edited in quince. Generally speaking, the main application for quince is the creation and editing of sequences of events in time.
Thus, the great thing about quince is not only what it already can do, but also how easy it is to add new functionality. quince was developed from a point of view which assumes that a software for artisic tasks is always insufficient. There are always some features missing and it almost never can exactly do what you need. Standard daws and sequencers are stable, powerfull and convenient, but they are also inflexible, in most cases not extensible and for many tasks which are a bit off the main road, they are simply useless. quince is not a substitution for a daw. If you're looking for a convenient tool to arrange sounds and mix tracks, there are already some wonderful solutions out there. quince is something different.
The biggest difference between quince and the standard daw is that quince does not operate in the 'tape recorder vs mixing desk'-paradigm. In quince there are no channels in which audio data is arranged, and since there are no channels, there also is no need for a mixer to mix them. Instead, quince presents it's contents in display strips which can contain arbitrary numbers of layers of data.
Another big difference is that quince is not limited to the processing of audio data. quince is able to handle all time based data types. Whether an event represents a video clip, an audio file, or whether the event should trigger the execution of a shell script is dependent only on the existence of an appropiate plug-in. Please read on to learn why.
quince is based on a core, which handles basic operational tasks such as file and object management, but which does not implement functionality that you can actually use to work on sequences of events. The core does however provide an interface for plug-ins. Almost all of the functionality of quince is implemented in plug-ins: There are display plug-ins (ContainerViews and ChildViews), function plug-ins (Functions) and player plug-ins (Players). quince is designed to be extensible, the interface to the core (the Quince API) is very flexible and the amount of code that needs to be written to add a new plug-in is minimal. quince may be an option for all those who have their own ideas on how to treat their data, who are not satisfied with standard solutions and for those who are able to write a few lines of code to implement custom functions on their own.
quince manages all the data of a session (file) in the pool. The pool contains two tables: a table with objects created by the user (on the left) and a table containing functions and function graphs (on the right).
Below the tables there are a few buttons:
Fold Selection
Please read the chapter fold/unfold below for more information.
Remove Selection
Deletes the selected objets.
New Data File
Creates a new object of type DataFile, which can represent any file type.
New Object
Creates a new object of type QuinceObject with standard parameters.
Copy Selection
Duplicates the selected objects.
New Audio File
Creates a new object of type AudioFile with a reference to an audio file on disk.
New Object For Audio File
When an AudioFile is selected in the pool: Creates a new object of type QuinceObject with a reference to the selected AudioFile object. Read the chapter AudioFiles below for more information.
Execute
Executes the selected function.
Since version 0.9.6 the pool automatically hides items (objects and functions) if they are incompatible with the selection in the other table respectively. To reset the hidden items press Command+Option+C.
In quince, data is represented in the form of objects, most of the are of type QuinceObject. A QuinceObject is just a collection of parameters. A QuinceObject with default parameters is an event, with a start, a duration, a name and a description. An event can contain other events (subEvents or subObjects). An event with subEvents is called a sequence, but it still is an object of type QuinceObject.
Parameter
A parameter is a pair of an identifier (key) like "volume" and a value, like -9dB. Every object has a few standard parameters like name, start, duration and type, can have any number of parameters and apart from a few reserved identifiers you can add any parameter to an object. (See Appendix A for a list of reserved parameter identifiers.)
To see the parameters of an object, to change their values or to add a new parameter to the object, select the object and open the inspector by clicking on the inspector icon in the toolbar.
SubEvents
Every event can have subEvents. In quince there is no direct differentiation between a sequence and the events a sequence consists of. A sequence simply is an event with subEvents. Accordingly, an event can contain subEvents which themselves contain subEvents and so on. There is no limit to the depth of the object tree.
Strips
A strip is an area where layers can display data. A quince session can contain any number of strips. When there is more than one strip in a session, there is one active strip which reacts to user input (keyboard and/or mouse). The active strip is marked with a blue frame. To create a new strip click on "Add Strip" in the toolbar. To remove the active strip, click on "Remove Strip". A strip is represented in a StripController (which essentially is a table with LayerControllers) which has buttons to add or remove layers.
A layer is where objects can actually be displayed and edited. Layers are represented in a LayerController, containing a pop-up for choosing a ContainerView (see next chapter for more information on ContainerViews), a button to load an object into the layer, a check box to hide/unhide the layer and a text field with the name of the currently loaded object. 
A layer has to be active in order to react to user input. To make a layer active, click in an empty area in the LayerController. The LayerController will become a little brighter and the layer will become active. The position of the layer in it's strip is irrelevant in this context. You can always edit any layer, even if some other layers are displayed in front of the one you want to edit.
To create a new layer or to remove the active layer of a strip click on "+" or "-", respectively, in the lower part of the StripController.
On the left to the "-" and "+" , you can activate/deactivate guides in the strip and specify the range of the values, visible in the strip (vertical zoom).
ContainerViews and ChildViews
If there is an object loaded in a layer, it is being displayed by a ContainerView. ContainerViews are plug-ins that allow the display and editing of certain types of objects. If the loaded object contains subEvents and if the selected ContainerView supports it, the object's subEvents will be displayed too, using ChildView objects which can be selected and edited inside the ContainerView.
To load an object into a ContainerView select a ContainerView in the LayerController, select an object in the object table of the pool and click on "load" in the LayerController of the layer you want the object to be loaded into.
Some ContainerViews can only display certain types of objects. For instance, the ContainerView "EnvelopeContainer" can only dispay objects of type Envelope. It will present an error message if you try to load any other type of object.
For more information on the behaviour of ContainerViews, please read the chapter ContainerViews in the Plug-In Reference.
The following integrated types are available:
AudioFile, a reference to an AudioFile on disc
DataFile, a reference to any kind of file on disc
Envelope, an object containing an array of volume values, typically generated analyzing an AudioFile
PitchCurve, an object containing an array of frequency values
QuinceObject, the most basic object type in quince, that represents an event, or a sequence
In a future version, you will be able to integrate your own types as plug-ins into quince.
Events can be folded to a sequence. If you choose to fold a number of selected objects, a new event is created and the selected objects are added as subObjects to the new object. To fold selected objects in a ContainerView press 'f'. To unfold a previously folded object in a containerView press Shift+'f'. (Actually it depends on the implementation of the respective ContainerView plug-in if subObjects can be folded and unfolded. The VolumeStandardContainer supports the folding of objects whereas the AutomationContainer, for instance, does not.)
Two selected objects…
...
folded into an new object.
You can also fold objects directly in the pool. Select the objects you want to fold in the objects table of the pool and press the button labeled "Fold Selection".
A function is a plug-in that carries out an operation. Functions can be executed out of the pool, or by selecting the function from one of the two function menues "Selection" and "Functions". In the "Selection" menu, only those functions are available which can be directly executed on a selection of subObjects in a ContainerView. In the "Function" menu, all the Functions are available.
Most functions operate on objects which are handed over to them. If one starts a function, the FunctionLoader pops up. The FunctionLoader manages the ‘delivery’ of objects to functions. It contains a list of objects the function expects. Each input object is described with the expected type and the purpose of the object during the execution of the function.
The function started in this example expects a single object of type AudioFile. It's purpose for the function is described as "source". To hand over an appropiate object to the FunctionLoader, select the object in the pool and click on "Load" in the FunctionLoader window. The object will now be handed over to the FunctionLoader and it will show up in the object list:
If all of the required objects are present, the "Action" button becomes active and the function can be executed.
Functions which expect a single input object of type QuinceObject with the purpose "source" can be started from the "Selection" menu to operate on a selection of objects in a ContainerView directly (without the FunctionLoader popping up).
Just like events can be folded into a sequence, you can combine functions into bigger objects called FunctionGraphs. You can only combine two functions at a time, but since a FunctionGraph acts just like a Function, you can combine a function with a FunctionGraph or a FunctionGraph with another FunctionGraph to create very powerful and complex tools.
Two functions get combined by linking the output of a first function to the input of a second. For two functions to be able to be combined into a FunctionGraph, the type of the output of the first function must match the type of one of the input objects of the second function.
To open the FunctionComposer click on it's icon in thetoolbar.
In the FunctionComposer, choose the source and target functions. If the two functions are compatible, possible connecting objects (matching input objects of the target function) will be displayed in the third pop-up (labeled "Input"). In the example above, the function "Audio2Envelope" is being combined with the function "ApplyEnvelope".
The result of "Audio2Envelope" is an object of type Envelope. The function "ApplyEnvelope" expects an input object of type Envelope with the purpose envelope and a QuinceObject with the purpose "target". The only matching object is the envelope. In the text field you can enter the name of the resulting FunctionGraph. Click on the button labeled "Create FunctionGraph" to create the FunctionGraph. It will be added to the function table of the pool.
If the new FunctionGraph is executed, the FunctionLoader asks for two objects:
The function Audio2Envelope needs an object of type AudioFile, the function ApplyEnvelope, in addition to the envelope provided by Audio2Envelope, needs an object of type QuinceObject with the purpose "target" on which the envelope should be applied.
Below the StripControllers there is a small black text field. By default it contains the string "no reference".
If you load an audio file into the pool and select it, the text in the text field changes to the name of the selected audio file object.
This indicates that you now have a refence to an audio file object: SubObjects created in a ContainerView whilst having a reference to an audio file object will get an additional parameter with the identifier "MediaFileName". It's value will be the name of the selected audio file object. If the session is played back (and if an appropiate player is chosen), the subObject's refered audio file will be played. Of course you can remove the reference at any time.
You can also create an object with a reference to an audio file directly in the pool. Select the audio file object you want to create a reference for and click on "New Object For Audio File". If you now load this object into a containerView and play back the session, the refered audio file will be played only if the object contains subObjects without media (audio) file references of their own. To create such subObjects simply deselect the audio file object in the pool (if not already done) and double click in the layer containing the object with the refence to the audio file. Create a few subObjects of reasonable duration. If you now play back the session these subObjects become windows into the audio file: they inherit the audio file reference of their mother object and play it back using their own start, duration and volume parameter values.
A player is a plug-in that plays back the session. Directly beneath the text field for the media file reference display, there is a pop up for the selection of a player.
Some players will allow you to change their behaviour. Use the settings button on the right to the menu to get access to a player's settings panel.
ContainerViews are plug-ins which display objects in a layer. For information on layers and on how to load an object into a layer, please read the chapter Layers above.
There are a few commands almost all ContainerViews understand. However, whether one particular ContainerView understands these commands depends on it's implementation.
Common ContainerView Commands
Keyboard:
f / Shift + f
folds / unfolds selected subObjects.
m
mutes / unmutes selected subObjects.
SPACE
starts / stops playback.
ENTER
during playback: creates a new subObject at the current play back position.
or else: resets the cursor to 00:00:000.
TAB
selects the next subObject.
Shift + TAB
selects the previous subObject.
Mouse
Double Click
creates a new subObject.
Mouse & Keyboard
Option-Drag
duplicates the selected subObjects.
Control-Drag
changes the duration of the selected subObjects. You can also pull on the right end of ChildViews for the same result.
The AutomationContainer provides an interface for the creation and editing of automation data.
However, there is no plug-in that processes automation data. (Yet!)
The CentContainer provides an interface for the display and editing of cent deviation values of objects with frequency data.
The EnvelopeContainer plug-in displays objects of type Envelope. The resolution of the display changes with the zoom. You do not always see the same resolution, but you always see the same amount of detail (envelope frames per pixel) :
There is a function plug-in called ResampleEnvelope. Use it to limit the resolution of an envelope.To change the display colour of an envelope, double click on the envelope. Then choose a colour in the colourpicker.
FrequencyStandardContainer
The FrequencyStandardContainer works in the same way as the VolumeStandardContainer, except that is displays frequency (linear) on its y-axis.
The GlissandoContainer displays objects using the GlissandoChild view:
It uses the parameter pitchF (a floating point representation of midi pitch) for the positioning of objects on its y-axis, and the parameter pitchRange for their height.
Glissandi are organized using three parameters: frequency, frequencyB and glissandoDirection. The glissandoDirection parameter determines which frequency value will be the start point and which one will serve as the end point of the glissando. However, the value of the parameter frequencyB must and will always be higher than the value of the parameter frequency. Quince will swap the frequency and frequencyB values and toggle the glissandoDirection automatically, if necessary. See the GlissandoChild reference for more information.
The MarkContainer provides a view for markings:
The PitchContainer works in the same way as the VolumeStandardContainer, except that is displays pitch (midi pitch, logarithmic frequency) on its y-axis.
The PitchCurveContainer displays PitchCurves with the parameter pitch on the y-axis. The pitches in PitchCurves can not actually be edited using the PitchCurveContainer. Just as the EnvelopeContainer, the PitchCurveContainer was made for display only.
The PitchGridContainer displays Pitches of a sequences subObjects independently from their respective start and duration values, as a grid. For a more detailed explanation how GridContainerViews work in quince, please see the TimeGridContainer reference below.
The TimeGridContainer displays sequences as a series of grid points in time (without durations). It is intended for the use in the process of quantizing sequences. (For more information on quantizing sequences please read the chapter Quantization in the Function Plug-In Reference.)
The TimeGridContainer displays the time points to which subObjects would be pulled if their surrounding sequence would be quantized using the displayed grid. In addition, it also displays the time frames from which subObjects would be pulled onto the grid points:
Here is another example with an additional layer of events:
After quantization with the displayed grid, the events are pulled to the grid points. In addition their durations will have changed accordingly:
The StandardVolumeContainer is a ContainerView with basic display and editing options for events. Events (subObjects) are displayed using the SequenceChild plug-in (ChildView) which displays objects as rectangular boxes which can be moved, extended, shortened, folded and unfolded. For more information on the SequenceChild plug-in please read it's description in the ChildView reference.
For information on how to execute functions and on how to pass an object to a function, please read the chapter Functions in the introduction above.
Functions, whose output object is not explicitly specified, do not create a new object as a result of their execution.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Sets the parameter frequency of all subObjects of the source to the frequency value of the subObject with the lowest start value.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Sets the parameter volume of all subObjects of the source to the volume value of the subObject with the lowest start value.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
|
|
|
The envelope which should be applied to the subObjects of the target.
|
Sets the parameter volume of all subObjects of the target to the value of the envelope at the time of the respective subObject's start value. It is recommended to resample the envelope before using this function. "ApplyEnvelope" performs resampling on it's own if the resolution of the envelope is higher than 5 ms per frame.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
|
|
|
The object whose values should be applied to the target.
|
Applies values of the source's subObjects (of a parameter chosen in a dialog) to the subObjects of the target.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
|
|
|
A DataFile object representing a text file with values to be added to the target's subObjects.
|
Interprets the contents of a text file as values for a parameter. The parameter is chosen in a dialog window. Each line in the text file is assigned to one subobject of the target as a value for the chosen parameter.
For example, if the textfile reads:
a
b
c
and you choose "name" as the parameter to assign values to and the target sequence has three subObjects, those three subobjects will be named "a", "b" and "c".
|
|
|
|
|
|
|
|
|
The AudioFile object from which the envelope should be extracted.
|
|
|
| |
|
|
| |
|
A new object with the envelope of the AudioFile object.
|
Reads the samples of the source and creates a new object of type Envelope containing the envelope of the AudioFile.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Lets the user chose a parameter:
After a choice is made, ChildViews representing the subObjects of the soure will be colored. Objects with the same values will get the same colors.
|
|
|
|
|
|
| |
|
|
|
|
| |
|
|
| |
|
A new object representing a grid for quantization.
|
Using this function you can create a grid for quantization.
There are too tabs within this function's window: One for the creation of time grids and one for creating pitch/frequency grids.
Time
The dividers refer to seconds. Using the checkboxes you can acivate or deactivate individual dividers. The default assignement represents standard musical divisions: if one second is one quarter note, the dividers correnspond to :
1: quarter note 2: 8th 3: tripplet (8th) 4: 16th 5: quintuplet (16th) 6: 6tuplet (16th) 7: 7tuplet (16th) 8: 32th
The resulting grid is displayed using colored bars:
Using the popup and the text field you can change individual dividers to create more complicated grids:
Click on Done to create a sequence with the specified grid. If you check the "repeat grid" box, the new object will be slightly longer than the longest obect in the pool.
Pitch
In the Pitch tab of the grid, you can create grids for the quantization of frequencies. Again there are two tabs: "Tempered" and "Other".
In the "Tempered" tab you can create grids using tempered scales of any resolution and you can specify which base frequency should be used for the grid:
|
|
|
|
|
|
|
|
|
The envelope whose values should be processed.
|
Removes all values below a threshold from the given envelope. The threshold can be specified in a dialog box.
The following envelope:
limited at -12dB:
EnvToSeq
|
|
|
|
|
|
|
|
|
The envelope to be converted.
|
|
|
| |
|
|
| |
|
A new object containing subobjects for significant changes in volume of the envelope.
|
EnvToSeq creates a Sequence containing objects for transients in the envelope. Upon execution you will be presented with the following dialog window:
EnvToSeq uses internal resampling of the envelope to measure volume values. After that it compares successive frames. The tolerance actually is the inverse ratio of two successive frames. The default duration is the duration of the newly created objects.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Creates an equal distribution of the subObjects of the source over the parameter frequency
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Creates an equal distribution of the subObjects of the source over the parameter pitch.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Creates an equal distribution of the subObjects of the source over the parameter start:
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Creates an equal distribution of the subObjects of the source over the parameter volume:
|
|
|
|
|
|
|
|
|
The object whose subobject's descriptions are to be exported.
|
|
|
| |
|
|
| |
|
A Text File containing a list of all the descriptions of the source's subobjects
|
Creates a text file containing all the descriptions of the source's sobobjects.
|
|
|
|
|
|
|
|
|
The object whose subObjects are to be analyzed.
|
|
|
| |
|
|
| |
|
A new Sequence containing subObjects representing the volume envelope of the source.
|
Creates a new sequence representing the volume envelope of the source. This will result in data reduction whenever there are multiple simultaneous objects in the source.
|
|
|
|
|
|
|
|
|
The object whose subObjects are to be analyzed.
|
|
|
| |
|
|
| |
|
A new Sequence containing subObjects representing frequency vertexes of the source.
|
Creates a new sequence with subObjects for each frequency vertex (change in frequency direction) in the source.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Sets the glissando end frequencies of the subobjects of the source (values of the parameter frequency or frequencyB)2 to the glissando start frequencies of the respective next subObject.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Sets the glissando start frequencies of the subobjects of the source (values of the parameter frequency or frequencyB)2 to the glissando end frequencies of the respective previous subObject.
FoldByParameter
|
|
|
|
|
|
|
|
|
The object to be processed.
|
Folds subobjects of the source object if they share the same value for a parameter chosen in a dialog window.
|
|
|
|
|
|
|
|
|
The object to be processed.
|
|
|
| |
|
|
| |
|
A new object containing copies of the subobjects of the source whose volume values are above a threshold.
|
Creates a copy of an object and removes all subobjects whose volume values are below a threshold.
|
|
|
|
|
|
| |
|
|
|
|
| |
|
|
| |
|
A new object with frequency data from a data file.
|
Asks for a file with frequency values and creates a new object with subObjects for the frequency values.
understands two file formats:
Spear: Text "Resampled Frames"
Praat: Text Formants in "TextFile"
ImportMaxMSPCollForSingleParameter
|
|
|
|
|
|
| |
|
|
|
|
| |
|
|
| |
|
A new object containing subobjects for significant changes in volume of the envelope.
|
Creates a new object containing subobjects with values from a MaxMSP coll file and default values specified in the following dialog:
|
|
|
|
|
|
|
|
|
The object whose subobject are to be joined.
|
|
|
| |
|
|
| |
|
A copy of the source whose subobjects are joined if successive object's frequencies are equal or within a given tolerance.
|
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Extends or shortenes the durations of the source's subObjects so that they follow up on each other without any gaps:
Exports the source as a source file for the LilyPond notation program (http://lilypond.org/). Each subObject of the source becomes one note. In a dialog box you can specify which parameters should be included in the code.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Adds dynamik expressions to subobjects of the source by choosing volume ranges. The LilyPondExport plug-in understands these expressions and can include them in the lilypond source.
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Normalizes the volume values of the source's subObjects, so that the subObject with the highest volume has the value 0dB.
|
|
|
|
|
|
|
|
|
|
|
|
| |
|
|
| |
|
A new object with copies of the loudest subobjects of the source that are not overlapping.
|
Creates a filtered version of the source, containing subobjects that are not overlapping. The subobjects are chosen by comparison of their volume values.
|
|
|
|
|
|
|
|
|
The grid on which the victim should be quantized.
|
|
|
|
The object whose subObject should be quantized.
|
Quantizes the victim onto the grid. PitchQuantization quantizes Frequency, Pitch and Cent values.
The frequency values of the subObjects of the victim are being pulled onto the frequency values of the subObjects of the grid.
See: PitchQuantization or TimeQuantization
|
|
|
|
|
|
|
|
|
The object whose subObjects should be changed.
|
Removes the selected parameter from all subObjects of the source and from the source itself.
|
|
|
|
|
|
|
|
|
The envelope whose resolution is to be limited.
|
In a dialog box you can specify a window duration (in milliseconds) to limit the envelope's resolution.
|
|
|
|
|
|
|
|
|
The object to transform into a PitchCurve
|
|
|
| |
|
|
| |
|
|
