{ "cells": [ { "cell_type": "markdown", "id": "697b464a-7222-45b4-943b-e33904921028", "metadata": {}, "source": [ "# The active wokspace\n", "\n", "There is always an active Workspace. When **maelzel.core** is imported a new Workspace is created, which can be retrieved via `getWorkspace`" ] }, { "cell_type": "code", "execution_count": 25, "id": "95c723c0-177c-4dbf-a6dd-a5b6e1e37d2d", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "Workspace(scorestruct=ScoreStruct(3/4, tempo=96), config={'play.instr': '.piano'}, dynamicCurve=DynamicCurve(shape=expon(0.3), mindb=-60.0, maxdb=0.0))" ] }, "execution_count": 25, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from maelzel.core import *\n", "from IPython.display import display\n", "\n", "w = getWorkspace()\n", "w" ] }, { "cell_type": "markdown", "id": "ba36df84-6945-46f2-8c82-72809f9e102f", "metadata": {}, "source": [ "Alternatively the active workspace can be accessed via the `active` class variable, as `Workspace.active`" ] }, { "cell_type": "code", "execution_count": 26, "id": "b416d830-cc6c-4a26-8488-ffbe271ef515", "metadata": {}, "outputs": [], "source": [ "w2 = Workspace.active\n", "assert w is w2" ] }, { "cell_type": "markdown", "id": "018b3445-9ecc-475c-b7b6-f1b2a46e88b8", "metadata": {}, "source": [ "The active workspace contains the working environment. The most important attributes encapsulated here are the score structure (`.scorestruct`, an instance of `ScoreStruct`) and the configuration (`.config`, an instance of `CoreConfig`) \n", "\n", "\n", "Each new `Workspace` contains a basic `ScoreStruct` (4/4, quarter=60) and a copy of the root config" ] }, { "cell_type": "code", "execution_count": 27, "id": "b84de978-257f-4046-8dd1-d2a3d4eeac23", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
ScoreStruct
| Meas. Index | Timesig | Tempo (quarter note) | Label | Rehearsal | Barline | Beats |
|---|---|---|---|---|---|---|
| 0 | 3/4 | 96 | 1+1+1 | |||
| 1 | (3/4) | 1+1+1 | ||||
| ... |
| Key | Value | Type | Descr |
|---|---|---|---|
| A4 | 442 | between 10 - 10000 | Freq. of A4. Normal values are between 440-443, but any value can be used |
| chordAdjustGain | True | type: bool | Limit the gain of a chord according to the number of notes, to prevent clipping. Only applied if the notes don't have an individual amplitude |
| dynamicCurveDynamics | ppp pp p mp mf f ff fff | type: str | Possible dynamic steps. A str with all dynamic steps, sorted from soft to loud |
| dynamicCurveMaxdb | 0 | between -160 - 0 | Amplitude in dB corresponding to the loudest dynamic |
| dynamicCurveMindb | -60 | between -160 - 0 | Amplitude in dB corresponding to the softest dynamic |
| dynamicCurveShape | expon(0.3) | type: str | Shape used for the converting dynamics to amplitudes. Normally an exponential curve, given as 'expon(exp)', where exp is the exponent used. exp < 1 results in more resolution for soft dynamics |
| enharmonic.horizontalWeight | 1 | type: int | Weight of the horizontal dimension (note sequences) when evaluating an enharmonic variant |
| enharmonic.verticalWeight | 0.5 | type: float | Weight of the vertical dimension (chords within a voice) when evaluating an enharmonic variant |
| fixStringNotenames | False | type: bool | True: pitches given as notenames are fixed at the spelling given. False: they are respelled for better readability within the context. Pitches given as midi notes or frequencies are always respelled |
| htmlTheme | light | {dark, light} | Theme used when displaying html inside jupyter |
| jupyterReprShow | True | type: bool | Render notation within the html repr within jupyter. If False, .show needs to be called explicitely to render notation |
| lilypondpath | | type: str | Path to the lilypond binary. If set, it must be an absolute, existing path. This needs to be set only when using a specific lilypond installation (lilypond is auto-installed if not found, see lilyponddist) |
| musescorepath | | type: str | Command to use when calling MuseScore. For macOS users: it must be an absolute path pointing to the actual binary inside the .app bundle |
| openImagesInExternalApp | False | type: bool | Force opening images with an external tool, even when inside a Jupyter notebook |
| play.backend | default | {alsa, auhal, default, jack, pa_cb, portaudio, pulse} | backend used for playback |
| play.defaultAmplitude | 1.0 | between 0 - 1 | Amplitude of a Note/Chord when an amplitude is needed and the object has an undefined amplitude, only used if play.useDynamics if False |
| play.defaultDynamic | f | {f, ff, fff, ffff, mf, mp, p, pp, ppp, pppp} | Dynamic of a Note/Chord when a dynamic is needed, only used if play.useDynamics is True. Any event with an amplitude will use that value instead |
| play.engineName | maelzel.core | type: str | Name of the play engine used |
| play.fade | 0.02 | type: float | Default fade time |
| play.fadeShape | cos | {cos, linear, scurve} | Curve-shape used for fading in/out |
| play.gain | 1.0 | between 0 - 1 | Default gain used when playing/recording |
| play.generalMidiSoundfont | | type: str | Path to a soundfont (sf2 file) with a general midi mapping |
| play.graceDuration | 1/14 | type: (int, float, str) | Duration assigned to a gracenote for playback (in quarternotes) |
| play.instr | .piano | type: str | default: sin | Default instrument used for playback. A list of available instruments can be queried via `presetManager.definedPresets()`. |
| play.numChannels | 2 | between 1 - 128 | Default number of channels (channels can be set explicitely when calling startPlayEngine |
| play.pitchInterpol | linear | {cos, linear} | Curve shape for interpolating between pitches |
| play.schedLatency | 0.05 | type: float | Latency when scheduling events to ensure time precission |
| play.soundfontAmpDiv | 16384 | type: int | A divisor used to scale the amplitude of soundfonts to a range 0-1 |
| play.soundfontFindPeakAOT | False | type: bool | True: find the peak of a soundfont to adjust its normalization at the moment an soundfont preset is defined |
| play.soundfontInterpol | linear | {cubic, linear} | Interpolation used when reading sample data from a soundfont. |
| play.unschedFadeout | 0.05 | type: float | Fade out when stopping a note |
| play.useDynamics | True | type: bool | True: any note/chord with a set dynamic will use dynamics to modify its playback amplitude if no explicit amplitude is set |
| play.verbose | False | type: bool | True: outputs extra debugging information regarding playback |
| quant.beatWeightTempoThresh | 52 | type: int | |
| quant.breakBeats | weak | {all, none, strong, weak} | Level at which to break syncopations. \"all\": break all syncopations; \"weak\": break syncopations over weak beats; \"strong\": only break syncopations at strong beats; \"none\": don´t break syncopations |
| quant.complexity | high | {high, highest, low, lowest, medium} | Complexity used for notation. |
| quant.gridWeight | None | between 0 - 10 | Weight applied to the time quantization error. Higher values result in more accurate quantization, at the cost of complexity. None sets this value from the complexity preset (quant.complexity) |
| quant.nestedTuplets | None | {False, None, True} | True: allow nested tuplets when quantizing. If None, this flag is set by the complexity preset (quant.complexity). Some backends (musescore) can't parse nested tuplets from musicxml atm |
| quant.nestedTupletsMusicxml | False | type: bool | False: no nested tuplets are used for musicxml. Some backends (MuseScore) don't render nested tuplets properly from mxml. Nested tuplets are used for other formats if \"quant.nestedTuplets\" = True |
| quant.subdivTempoThresh | 96 | type: int | |
| quant.syncopExcludeSymDurs | (5, 7, 15) | type: tuple | Durations with a numerator in this list cannot be placed across a beat. A value of (7, 15), for example, excludes double and trippled dotted notes |
| quant.syncopMaxAsymmetry | 3 | between 1 - 99 | Max. asymmetry of a syncopation. For notes across beats, this sets the max. allowed asymmetry across the beat, as a ratio longest:shortest part across the beat. A note exactly across the beat has an asymmetry of 1 |
| quant.syncopMinFraction | 1/6 | type: (str, float, Rational) | Min. duration of a syncopation as a ratio of the beat. Any syncopation shorter is broken and its parts tied, to prevent complex syncopations |
| quant.syncopPartMinFraction | 1/10 | type: str | Min. duration of any part of a syncopation, as a fraction of the beat. A syncopation consistings of two parts, one left and one right to the beat boundary |
| rec.blocking | True | type: bool | Should recording be blocking or should be done async? |
| rec.extratime | 0.0 | between 0.0 - inf | Default extratime added when recording |
| rec.ksmps | 64 | {1, 16, 32, 64, 128, 256} | Samples per cycle when rendering offline (passed as ksmps to csound) |
| rec.numChannels | 2 | between 1 - 128 | Number of channels when rendering to disk |
| rec.path | | type: str | Path used to save output files when rendering offline. If not given the default can be queried via `recordPath` |
| rec.sr | 44100 | {44100, 48000, 88200, 96000, 192000} | Sample rate used when rendering offline |
| rec.verbose | False | type: bool | Show debug output when calling csound as a subprocess |
| reprDurationAsFraction | True | type: bool | Show durations as fractions instead of floats |
| reprShowFreq | False | type: bool | Show frequency when printing a Note in the console |
| reprUnicodeAccidentals | True | {False, full, simple, True} | Use unicode accidentals for representation of notes |
| reprUnicodeFractions | False | type: bool | Show fractions (for durations/offsets) as unicode glyphs. Not all fonts have support for this |
| semitoneDivisions | 4 | {1, 2, 4} | Number of divisions/semitone used for notation (2=quarter-tones, 4=eighth-tones) |
| show.absOffsetWhenDetached | False | type: bool | When showing an object which has a parent but is shown detached from it, shouldthe absolute offset be used? |
| show.arpeggiateChord | auto | {auto, False, True} | Display chords as an arpeggio. In auto mode, only arpeggiate when needed |
| show.arpeggioDuration | 0.5 | type: float | Duration used for individual notes when rendering a chord as arpeggio |
| show.autoClefChanges | True | type: bool | True: add clef changes to a quantized part if needed. Otherwise, one clef is determined for each part and is not changed along the part. |
| show.backend | lilypond | {lilypond, musicxml} | Method used when rendering notation |
| show.cacheImages | True | type: bool | True: cache rendered images. Set it to False for debugging. call `resetImageCache()` to reset manually |
| show.centSep | , | type: str | Separator used when displaying multiple cents deviation (in a chord) |
| show.cents | True | type: bool | Show cents deviation as text when rendering notation |
| show.centsTextSnap | 2 | between 0 - 50 | Pitches which deviate less than this cents from a quantized pitchdon´t need a text annotation (see `show.cents`) |
| show.centsTextStyle | fontsize=6; placement=below | type: str | Style used for cents annotations. A list of key=value pairs, separated by ;. Keys: fontsize, box (rectangle, square, circle), placement (above, below), italic, bold. Flags don´t need a value. Example: \"fontsize=12; italic; box=rectangle\" |
| show.clefChangesWindow | 1 | type: int | When adding automatic clef changes, use this window size (number of elements per evaluation) |
| show.clefSimplify | 0.0 | between 0 - 10000 | Simplifies automatic clef changes. Use higher values to limit clef changes |
| show.clipNoteheadShape | square | {cluster, cross, normal, rectangle, rhombus, slash, square, triangle} | Notehead shape to use for clips |
| show.dynamicFromAmplitude | False | type: bool | True: when rendering notation, if an object has an amplitude and does not have an explicit dynamic, add a dynamic according to the amplitude |
| show.flagStyle | straight | {flat, normal, straight} | Flag style, at the moment only valid in lilypond |
| show.format | png | {pdf, png, repr} | Used when no explicit format is passed to .show |
| show.glissHideTiedNotes | True | type: bool | Hide tied notes which are part of a glissando |
| show.glissLineThickness | 2 | {1, 2, 3, 4} | Line thikness when rendering glissandi. The value is abstract and it isup to the renderer to interpret it |
| show.glissLineType | solid | {solid, wavy} | Default line type for glissandi |
| show.glissStemless | False | type: bool | When the end pitch of a gliss. is shown as gracenote, make this stemless |
| show.hideRedundantDynamics | True | type: bool | Hide redundant dynamics within a voice |
| show.horizontalSpace | medium | {default, large, medium, small, xlarge} | Hint to adjust horizontal spacing. The actual result depends on the backend and the format used. |
| show.jupyterMaxImageWidth | 1000 | type: int | Max. width in pixels for images displayed in a jupyter notebook |
| show.keepClefBias | 2.0 | type: float | The higher this value, the more likely it is to keep the previous clef during automatic clef changes |
| show.labelStyle | fontsize=9; placement=above | type: str | Text size used for labelsA list of key=value pairs, separated by ;. Keys: fontsize, box (rectangle, square, circle), placement (above, below), italic, bold. Flags don´t need a value. Example: \"fontsize=12; italic; box=rectangle\" |
| show.lilypondGlissMinLength | 5 | type: int | Min. length of a glissando in points. Increase this value if gliss. linesare not shown or are too short if a gliss. collides with dots or accidentals |
| show.lilypondPngStaffsizeScale | 1.5 | type: float | Factor applied to the staffsize when rendering to png via lilypond. Useful if rendered images appear too small in a jupyter notebook |
| show.measureLabelStyle | box=rectangle; fontsize=12 | type: str | Style for measure annotations. A list of key=value pairs separated by ;. Keys: fontsize, box (rectangle, square, circle), placement (above, below), italic, bold. Flags don´t need a value. Example: \"fontsize=12; italic; box=rectangle\" |
| show.musicxmlFontScaling | 1.0 | type: float | Scaling factor applied to font sizes when rendering to musicxml |
| show.pageMarginMillim | 4 | between 0 - 1000 | Page margin in mm |
| show.pageOrientation | portrait | {landscape, portrait} | Page orientation when rendering to pdf |
| show.pageSize | a4 | {a2, a3, a4} | Page size when rendering to pdf |
| show.pngResolution | 200 | {100, 200, 300, 600, 1200} | DPI used when rendering to png |
| show.proportionalDuration | 1/24 | type: str | When using proportional spacing, the lower this value, the longer the space taken by each note. This corresponds 1:1 to the value as used by lilypond. See also: https://lilypond.org/doc/v2.23/Documentation/notation/proportional-notation |
| show.referenceStaffsize | 12.0 | type: float | Staff size used as a reference to convert between staff size and scaling factor. This allows to use staff size as a general way to indicate the scale of a score, independent of the backend |
| show.rehearsalMarkStyle | box=rectangle; fontsize=13; bold | type: str | Style for rehearsal marks. A list of key=value pairs, separated by ;. Keys: fontsize, box (rectangle, square, circle), placement (above, below), italic, bold. Flags don´t need a value. Example: \"fontsize=12; italic; box=rectangle\" |
| show.respellPitches | True | type: bool | True: find a suitable enharmonic representation for pitches within their context. False: the canonical form of eachpitch is used, independent of the context |
| show.scaleFactor | 0.75 | type: float | Affects the size of the generated image when using png format |
| show.scaleFactorMusicxml | 0.8 | type: float | Apply a scaling factor to images rendered via musicxml |
| show.spacing | normal | {normal, strict, uniform} | Kind of spacing used. \"normal\": traditional spacing; \"uniform\": proportional spacing with uniform stretching; \"strict\": proportional spacing with strict placement (clef changes and bar lines don´t add spacing andmight overlap) |
| show.staffSize | 10.0 | type: float | Size of a staff, in points |
| show.voiceMaxStaves | 2 | between 1 - 4 | Max. number of staves per voice when showing a Voice as notation. Even thougha voice is a sequence of non-simultaneous events (notes, chords, etc.), these canbe exploded over multiple staves |
| show.warnIfEmpty | True | type: bool | True: warn if an object did not produce any scoring parts |
| soundfilePlotHeight | 3 | type: int | Height used for plotting soundfiles. This is used, for example, to set the figsize in matplotlib plots used inline within Jupyter. |
| splitAcceptableDeviation | 4 | type: int | When splitting notes between staves, notes within this range of the split point will be grouped together if they all fit |
| .enharmonic.150centMicroPenalty | 20 | type: int | |
| .enharmonic.debug | False | type: bool | True: print debug information while calculating automatic enharmonic spelling |
| .quant.complexityWeight | None | between 0 - 10 | Weight applied to the complexity of the rhythm during quantization. A higher value results in simpler rhythms. None sets this value from the complexity preset (quant.complexity) |
| .quant.debug | False | type: bool | Output extra debug info during quantization, showing how different divisions are evaluated by the quantizer |
| .quant.debugShowNumRows | 50 | type: int | When quantization debugging is turned on this setting limits the number of different quantization possibilities shown |
| .quant.divisionWeight | None | type: NoneType | Weight applied to the penalty of the beat divisionHigher values result in simpler subdivisions. None to use the value set by the complexity preset (quant.complexity) |
| .quant.gridErrorExp | None | type: NoneType | Exponent applied to the grid error. The error is a value between 0-1 showing the grid accuracy for a given quantization (0=perfect timing). A value between 0-1 makes grid errors weight more. None to use the value set by the complexity preset (quant.complexity) |
| .quant.mergeTupletsDifferentDur | False | type: bool | |
| .rec.compressionBitrate | 224 | type: int | default bitrate to use when encoding to ogg or mp3 |
| .show.centsTextPlusSign | True | type: bool | Show a plus sign for possitive cents deviations |
| .show.dynamicsResetAfterEmptyMeasure | True | type: bool | |
| .show.dynamicsResetAfterRest | 1 | type: int | |
| .show.dynamicsResetTime | 32 | between 0 - 999999999 | When removing redundant dynamics, reset after this number of quarters |
| .soundfilePlotWidth | 24 | type: int |
\"/home/em/.local/share/maelzel/recordings/rec-2025-09-26T19:25:01.585.wav\", 1 channels, 3.52 secs, 44100 Hz)3.52, sr: 44100, numchannels: 1)\"/home/em/.local/share/maelzel/recordings/rec-2025-09-26T19:25:37.221.wav\", 1 channels, 2.21 secs, 44100 Hz)2.21, sr: 44100, numchannels: 1)Chain([4C:1/2♩, 4D:2♩, 4E:1♩], dur=3.5)Chain([4C:1/2♩, 4D:2♩, 4E:1♩], dur=3.5)\"/home/em/.local/share/maelzel/recordings/rec-2025-09-26T19:27:21.767.wav\", 1 channels, 3.11 secs, 44100 Hz)3.11, sr: 44100, numchannels: 1)Chain([4C+15:1♩, 4E♭-19:1/2♩, 3B+:3/2♩], dur=3)Chain([4C+15:1♩, 4E♭-19:1/2♩, 3B+:3/2♩], dur=3)Chain([4C+15:1♩, 4E♭-19:1/2♩, 3B+:3/2♩], dur=3)