Ncode
Interactive Score Building in Opusmodus
This document explains how NCODE works from a user’s point of view, focusing on its two main areas: the Function and Variables window and the Def-Score pane. It is for anyone who wants to explore algorithmic composition in Opusmodus without writing Lisp code.
The document has five sections: Introduction; Function and Variables window; Def-Score pane; Typical workflows; and Conventions and troubleshooting.
1. Introduction
NCODE is an interactive workspace in Opusmodus for exploring functions and building musical ideas step by step. It lets you:
adjust a function’s inputs using simple on-screen fields,
save results as named variables you can reuse later, and
assemble a complete score using the Def-Score pane.
1.1 Terminology
Variable: a named value stored in the NCODE history.
History: the ordered list of stored variables within the current session.
OMN variable: a variable whose value is an OMN event sequence and can be assigned to an instrument in Def-Score.
Session: the complete NCODE state saved as an .omnc file.
1.2 Creating, opening, and saving NCODE sessions (.omnc)
NCODE sessions are stored as .omnc files. A session file preserves the complete NCODE state (including the history, variable bindings, and Def-Score settings).
1.2.1 Creating a new session
To start a new NCODE session file:
1. Choose New → NCODE Session…
2. The session file is created in ~/Opusmodus/Media/Ncode/.
3. The NCODE window opens automatically.
1.2.2 Opening an existing session
An existing .omnc file can be opened in two ways:
• From the Navigator: open the Media/Ncode folder and select the desired .omnc file.
• From the Open command: choose Open and select the required .omnc file.
1.2.3 Saving edits
To save changes made in the NCODE window, use Save. This updates the currently open .omnc session file.
2. Function and Variables window
The Function and Variables window is the primary workspace for exploration. It combines a history of generated materials with an input form for defining and evaluating function calls. Figure 1 provides the reference layout.
Figure 1. NCODE main window: Function and Variables.
2.1 Variables pane
The upper table lists variables created in the current session. Selecting a row recalls the variable’s originating function and parameters, allowing the computation to be reproduced, modified, or re-evaluated.
2.1.1 Filter controls
The filter buttons restrict the table to a variable class, supporting rapid navigation in large sessions:
All: display all stored variables.
Numbers, Lengths, Pitches, Velocities, Articulations: display variables whose values are classified accordingly.
OMN Events: display OMN event variables intended for score construction.
Edited: display only variables that have been modified since the last save.
2.1.2 History table columns
Each variable entry is described by structured metadata:
Type: the variable class recognised by NCODE.
Name: the variable symbol stored in the session.
Preview: the function associated with the variable’s creation.
Size: an estimate of the value’s extent (for example, list length).
Category and Operation: functional descriptors for orientation.
Edited: a mark indicating that the entry differs from its saved state.
2.1.3 History operations
Refresh All: re-evaluate all history entries in creation order, restoring the session’s bindings. This is essential prior to Def-Score compilation when the score references stored variables. The command remains available after using New, and is disabled only when the session contains no variables.
Variables: open history management (reorder entries and remove selected variables).
Clear All: remove all variables from the session history (after confirmation).
Define Score: open the Def-Score pane.
Save to File: export the current history to an Opusmodus source file.
Contextual menu (History table)
Display and editing actions are accessed from the history table via a contextual menu (right-click). The menu is type-sensitive: it offers only the renderers and actions that are meaningful for the selected variable. Typical commands include:
Snippet and Graph renderers (where supported),
Notation, MIDI Player, and Live Coding for OMN materials,
Export to Editor to insert the value or its generating expression into the editor,
Edit actions for structured modification where applicable.
Figure 2 shows the contextual menu for an OMN variable, including Notation,
Multiple Voices, MIDI Player and Live Coding
2.2 Function pane
The Function pane specifies a function call through explicit argument fields. NCODE automatically presents required and optional parameters when a function is selected.
2.2.1 Name and Function fields
Name (variable): optional. When provided, the evaluation result is stored under this symbol; when omitted, NCODE generates an automatic name when adding to history.
Function: the function identifier; in-place completion supports efficient selection.
New: reset the Function pane to a safe empty state by clearing Name, Function, and all argument fields, and by deselecting any active variable in the history. This prevents unintended overwriting of an existing variable when Apply is used.
Doc: open the documentation entry for the selected function.
Edit: open the current argument expression in the editor for structured editing.
Contextual variable insertion (Function and Argument fields)
To reuse existing history variables while composing a new function call, NCODE provides a contextual insertion menu in the Function and Argument fields.
How to use: right-click inside the Function field or an argument field to open a contextual menu of available history variables.
Insert behaviour: selecting a variable inserts its name at the current caret position. The existing field text is preserved (it is not replaced).
Purpose: this supports rapid reuse of previously computed materials without recalling (loading) the variable’s originating function.
Notes: insertion is purely textual. It does not evaluate the function and it does not alter the history selection.
2.2.2 Argument fields
Argument fields correspond to the function signature. Fields marked as required must be supplied. Optional and keyword parameters may be left empty to omit them.
2.2.4 SETF mode, templates, and pages
NCODE provides a template-driven mode for constructing structured values via SETF pages. This mode is used when the Function field is SETF and a template is selected. Rather than entering a single expression, the user fills a set of pages; NCODE then reconstructs a quoted value and evaluates a (setf …) form.
Figure 3 SETF mode, templates and pages.
SETF pages provide a UI method for building complex, repeatable list structures (collections of labelled items) without manual list syntax. This is particularly useful when the value is naturally expressed as multiple items that must be ordered.
Templates
A template defines:
the number and organisation of pages, and
the fields available on each page (key–value pairs).
Selecting a different template changes the page layout and the meaning of the fields. The selected template and page contents are saved in the .omnc session and restored when reopened.
Page navigation and editing
Next page: creates a new item (page) and moves the view forward.
Previous: moves to the preceding page without creating or removing items.
Remove page: removes the current page (item).
Empty pages are ignored when the final value is constructed.
Field values
Fields accept numbers, strings, keywords, lists, and symbols.
Symbols entered without a leading quote may be treated as variable references (for example, previously stored history variables).
When a literal symbol is required, enter it as a quoted symbol.
Constructed value
When evaluated, NCODE converts the populated pages into a single quoted form:
if one page is populated, the value becomes a quoted single item;
if multiple pages are populated, the value becomes a quoted list of items.
NCODE then evaluates the corresponding (setf …) form, storing the result in the history like any other entry.
Reproducibility
SETF pages are stored as structured page data in the session. When reloading a session or using Refresh All, NCODE reconstructs the same quoted value from the saved pages and re-establishes consistent bindings.
2.2.3 Evaluation and recording
Evaluate: evaluate the function with the current arguments without adding a history entry.
Apply: evaluate the function and add (or update) the result in the history. If Name is empty, NCODE generates a name; the repeat selector determines how many evaluations are appended.
Repeat selector: specifies how many history variables are created when using automatic naming.
Code: insert the corresponding function call into the editor without evaluating it.
Clear Editor: clear the editor contents.
2.3 Editor and argument editing
The editor serves as a log of inserted code and evaluation output. It also supports safe editing of complex arguments. When Edit is used, NCODE places the selected argument expression into the editor and switches into an argument-edit mode: the updated text can be applied back to the argument field, or cancelled to restore the previous state.
2.4 Display and contextual rendering
NCODE provides type-specific rendering for stored variables. Rendering does not modify values; it presents the current binding using an appropriate view (notation, MIDI playback, graphs, or excerpts). Rendering is invoked from the contextual menu of the history table. The available renderers depend on the selected variable type; for OMN variables, common targets include notation views, MIDI playback, and live-coding, the menu may also provide a Multiple Voices renderer when the material is suitable for multi-voice presentation.
3. Def-Score pane
The Def-Score pane constructs a complete score definition by combining global defaults, layout definitions, and instrument assignments. It is typically used after generating one or more OMN variables in the main window. Figure 4 provides the reference layout.
Figure 4. Def-Score pane with Defaults, Layout items, and Instrument items.
3.1 Defaults section
The Defaults section specifies score metadata and global settings. The score name is required; other fields provide title data and global musical parameters such as key signature, time signature, and tempo.
Score name (required): the symbolic identifier of the score.
Title fields: title, subtitle, composer, writer, and copyright.
Def-Score defaults: key-signature, time-signature, tempo, and related engraving settings (e.g., accidentals and clef behaviour).
Range fields: start and end delimiters where supported.
3.2 Layout items section
Layout items define how instruments are organised into staves and groups. Each entry specifies a layout template and the instruments to which it applies, together with optional display names and abbreviations.
Layout items list: shows the current layout entries; selection loads an entry for editing.
layout: select a layout template (e.g., percussion layout).
instrument: list of instruments associated with the selected layout entry.
Add, Delete: create or remove entries.
Up, Down: reorder entries to control staff order.
3.3 Instrument items section
Instrument items bind musical material to instruments and set playback parameters. The OMN field is required and selects an OMN variable from the session history.
Instrument items list: shows defined instruments; selection loads an entry for editing.
instrument: the instrument identifier used throughout the score.
omn (required): the OMN variable assigned to the instrument.
MIDI settings: port, channel, sound set, and program.
Performance controls: controllers, pan, and volume, where used.
Add, Delete, Up, Down: manage the instrument list and its ordering.
3.4 Output actions
The bottom row evaluates and renders the score using the chosen backend.
Refresh All: refresh bindings by re-evaluating the session history prior to score compilation.
Notation: compile and open a notation view.
MIDI Player: compile and open a MIDI player view.
Live Coding: compile and open a live-coding workflow for performance or iteration.
Close Def-Score: return to the Function and Variables window.
4. Typical workflows
4.1 Exploratory function study
A standard exploratory cycle proceeds as follows:
If you are beginning a new exploration after recalling an existing history entry, use New to clear the fields and deselect the active variable before entering a fresh function call.
Select a function in the Function field and supply required arguments.
Select a function in the Function field and supply required arguments.
Use Evaluate to inspect output without recording results.
Use Apply to retain a result as a variable when it is musically useful.
Recall stored variables by selecting them in the history table, then adjust parameters to study sensitivity.
Use the history table’s contextual menu to audition or visualise results (e.g., notation, MIDI player, graphs, or live coding), depending on the variable type.
4.2 Building a score from OMN materials
Score construction typically begins with one or more OMN event variables:
Generate OMN variables in the main window and confirm them via the history table’s contextual menu (notation and/or MIDI playback).
Open the Def-Score pane using Define Score.
Specify Defaults (score name, tempo, time signature, and any engraving settings).
Define Layout items to organise the desired staff structure.
Add Instrument items and assign each to an OMN variable via the omn selector.
Select Notation or MIDI Player to compile and render the score.
4.3 Reproducibility and session refresh
NCODE stores computations as a history of variable definitions. When reopening a session, or after editing earlier variables, later results may depend on updated bindings. The Refresh All command restores a consistent state by re-evaluating the history in order, ensuring that Def-Score compilation and display operate on current values.
4.4 Exporting and interoperability
NCODE supports two complementary export paths: (i) exporting the variable history to an Opusmodus source file for code-centric workflows, and (ii) compiling a score through Def-Score for notation, MIDI playback, or live coding. In both cases, the session history provides a traceable provenance of generated materials.
5. Conventions and troubleshooting
5.1 Required fields and evaluation failures
Fields marked as required must be supplied. Missing required arguments prevent evaluation.
Def-Score compilation requires that referenced OMN variables are currently bound; if the score fails to compile after reopening a session, use Refresh All in the main window before attempting output.
If an argument expression is complex, use Edit to revise it in the editor and apply the update back to the argument field.
5.2 Naming and history management
Use the Name field when stable identifiers are required (for example, when multiple instruments refer to the same material).
Use the history management dialogue to reorder or remove variables when curating a session for publication or teaching.
The Edited filter supports rapid auditing of changes prior to saving or exporting.