| I have completed a preliminary implementation of a complete suite of
Jack opcodes. The initial documentation may be found below, and the
unit test CSD is attached. The code and unit test are in Csound CVS.
Thanks to everyone who helped me with suggestions or criticism,
especially Fons Adriaenson.
This was tested with jackd 0.109.2 as that is what came with my by now
old installation of Eeebuntu. I plan to upgrade this soon.
To sum up, you can query Jack for ports and connections; connect MIDI
and audio ports outside Csound to Csound in any configuration; stop,
start, and reposition the Jack transport; and turn the freewheeling
mode of Jack on and off, which enables rendering scores to soundfile
without dropouts that would have xruns or simply crash Jack in real
time. The whole system is independent of the command-line Jack system,
and more flexible.
I may add another opcode to connect one external port to another
external port; then Python or Csound's system opcode could be used to
create and run a complete Jack session of multiple applications.
The opcodes seem to do everything that I need for working with
algorithmic composition for Jack-enabled synthesizers and Csound.
I'm sure there will be bugs and fixes to do, so please feel free to
email me with bug reports, questions, or anything else.
Regards,
Mike
/**
* T H E J A C K O P C O D E S
* Michael Gogins
*
* The Jack opcodes can be used to connect any number
* of Csound instances, instruments, or user-defined
* opcodes to any number of Jack ports
* in any number of external Jack servers.
* Audio and MIDI signal types are supported.
*
* Sending MIDI and/or audio to external Jack clients,
* such as synthesizers, and receiving audio and/or
* MIDI back from them, is supported.
*
* Receiving MIDI and/or audio from external Jack clients,
* such as sequencers, and sending MIDI and/or audio
* back to them, is supported.
*
* Other uses also are supported.
*
* O P C O D E S
*
*
* JackoInit -- Initializes Csound as a Jack client.
*
* Description
*
* Initializes this instance of Csound as a Jack client.
*
* Csound's sr must be equal to the Jack daemon's
* frames per second.
*
* Csound's ksmps must be equal to the Jack daemon's
* frames per period.
*
* Frames per period must not only (a) be a power of 2,
* but also (b) go evenly into the frames per second,
* e.g. 128 frames per period goes into 48000
* frames per second 375 times, for a latency or
* MIDI time granularity of about 2.7 milliseconds
* (as good as or better than the absolute best
* human performers).
*
* The order of processing of all signals that pass
* from Jack input ports, through Csound processing,
* and to Jack output ports, must be properly
* determined by sequence of instrument and
* opcode definition within Csound.
*
* Syntax
*
* JackoInit SclientName, ServerName
*
* Initialization
*
* SclientName -- The name of the Jack client;
* normally, should be "csound".
*
* ServerName -- The name of the Jack daemon;
* normally, will be "default".
*
* This opcode must be called once and only once in the
* orchestra header, and before any other Jack opcodes.
*
*
* JackoInfo -- Prints information about the Jack system.
*
* Description
*
* Prints the Jack daemon and client names, the
* sampling rate and frames per period,
* and all active Jack port names,
* types, states, and connections.
*
* Syntax
*
* JackoInfo
*
* Initialization
*
* May be called any number of times in the orchestra header,
* for example both before and after creating Jack ports
* in the Csound orchestra header.
*
*
* JackoFreewheel -- Turns freewheeling mode on or off.
*
* Description
*
* Turns Jack's freewheeling mode on or off.
*
* When freewheeling is on, if supported by the rest
* of the Jack system, Csound will run as fast as possible,
* which may be either faster or slower than real time.
*
* This is essential for rendering scores that are too
* dense for real-time performance to a soundfile,
* without xruns or dropouts.
*
* Syntax
*
* JackoFreewheel [ienabled]
*
* Initialization
*
* ienabled -- Turns freewheeling on (the default) or off.
*
*
* JackoAudioInConnect -- Creates an audio connection
* from a Jack port to Csound.
*
* Description
*
* Creates an audio connection from an external Jack
* audio output port to a Jack audio input port inside
* this instance of Csound.
*
* Syntax
*
* JackoAudioInConnect SexternalPortName, ScsoundPortName
*
* Initialization
*
* SexternalPortName -- The full name ("clientname:portname")
* of an external Jack audio output port.
*
* ScsoundPortName -- The short name ("portname")
* of the internal Jack audio input port.
*
* Performance
*
* The actual audio must be read with the JackoAudioIn opcode.
*
*
* JackoAudioOutConnect -- Creates an audio connection
* from Csound to a Jack port.
*
* Description
*
* In the orchestra header, creates an audio connection
* from a Jack audio output port inside this instance
* of Csound to an external Jack audio input port.
*
* Syntax
*
* JackoAudioOutConnect ScsoundPortName, SexternalPortName
*
* Initialization
*
* ScsoundPortName -- The short name ("portname")
* of the internal Jack audio input port.
*
* SexternalPortName -- The full name ("clientname:portname")
* of an external Jack audio output port.
*
* Performance
*
* The actual audio must be written with the JackoAudioOut
* opcode.
*
*
* JackoMidiInConnect -- Creates a MIDI connection from
* Jack to Csound.
*
* Description
*
* Creates a MIDI connection from an external Jack MIDI
* output port to this instance of Csound.
*
* Syntax
*
* JackoMidiInConnect SexternalPortName, ScsoundPortName
*
* Initialization
*
* SexternalPortName -- The full name ("clientname:portname")
* of an external Jack MIDI output port.
*
* ScsoundPortName -- The short name ("portname")
* of the internal Jack MIDI input port.
*
* Must be used in conjunction with the
* -M0 -+rtmidi=null Csound command-line options.
* Can be used in with the MIDI inter-operability
* command-line options and/or opcodes to enable the
* use of ordinary Csound instrument definitions to
* render external scores or MIDI sequences.
*
* Note that Csound can connect to ALSA ports through Jack,
* but in this case you will have to identify the port by
* its alias in the JackInfo printout.
*
* Performance
*
* The actual MIDI events will be received in the
* regular Csound way, i.e. through a MIDI driver
* and the sensevents mechanism, rather than through
* a Jack input port opcode.
*
* The granularity of timing is Csound's kperiod.
*
*
* JackoMidiOutConnect -- Creates a MIDI connection from
* Csound to Jack.
*
* Description
*
* In the orchestra header, creates a connection
* from a Jack MIDI output port inside this instance
* of Csound to an external Jack MIDI input port.
*
* Syntax
*
* JackoMidiOutConnect ScsoundPortName, SexternalPortName
*
* Initialization
*
* ScsoundPortName -- The short name ("portname")
* of the internal Jack audio input port.
*
* SexternalPortName -- The full name ("clientname:portname")
* of an external Jack audio output port.
*
* Performance
*
* The actual MIDI data must be written with the JackoMidiOut
* or JackoNoteOut opcodes.
*
*
* JackoOn -- Enables or disables all Jack opcodes.
*
* Description
*
* After all Jack connections have been created, enables
* or disables all Jack input and output opcodes
* inside this instance of Csound to read or write data.
*
* Syntax
*
* JackoOn [iactive]
*
* Initialization
*
* iactive -- A flag that turns the ports on (the default)
* or off.
*
*
* JackoAudioIn -- Receives an audio signal from a Jack port.
*
* Description
*
* Receives an audio signal from a Jack audio input port
* inside this instance of Csound, which in turn has
* received the signal from its connected external Jack
* audio output port.
*
* Syntax
*
* asignal JackoAudioIn ScsoundPortName
*
* Initialization
*
* ScsoundPortName -- The short name ("portname")
* of the internal Jack audio input port.
*
* Performance
*
* asignal -- Audio received from the external Jack
* output port to which ScsoundPortName is connected.
*
*
* JackoAudioOut -- Sends an audio signal to a Jack port.
*
* Description
*
* Sends an audio signal to an internal Jack audio
* output port, and in turn to its connected external
* Jack audio input port.
*
* Note that it is possible to send audio out via Jack
* to the system audio interface, while at the same time
* rendering to a regular Csound output soundfile.
*
* Syntax
*
* JackoAudioOut ScsoundPortName, asignal
*
* Initialization
*
* ScsoundPortName -- The short name ("portname")
* of the internal Jack audio output port.
*
* Performance
*
* asignal -- Audio to be sent to the external Jack audio
* input port to which CsoundPortName is connected.
*
* Audio from multiple instances of the opcode sending
* to the same Jack port is summed before sending.
*
*
* JackoMidiOut -- Sends a MIDI channel message to a
* Jack port.
*
* Description
*
* Sends a MIDI channel message to a Jack MIDI output port
* inside this instance of Csound, and in turn to its
* connected external Jack MIDI input port.
*
* Syntax
*
* JackoMidiOut ScsoundPortName, kstatus, kchannel, kdata1[, kdata2]
*
* Initialization
*
* ScsoundPortName -- The short name ("portname")
* of the internal Jack MIDI input port.
*
* Performance
*
* kstatus -- MIDI status byte; must indicate a MIDI channel
* message.
*
* kchannel -- MIDI channel (from 0 through 15).
*
* kdata1 -- First data byte of a MIDI channel message.
*
* kdata2 -- Optional second data byte of a MIDI channel message.
*
* This opcode can be called any number of times
* in the same kperiod. Messages from multiple instances
* of the opcode sending to the same port are collected
* before sending.
*
* Running status, system exclusive messages, and
* real-time messages are not supported.
*
* The granularity of timing is Csound's kperiod.
*
*
* JackoNoteOut -- Send one note to a Jack MIDI port.
*
* Description
*
* Sends one note to a Jack MIDI output port inside this
* instance of Csound, and in turn to the connected external
* Jack MIDI input port, with a duration
* specified by the score instrument statement.
* The matching MIDI note off message is generated
* and scheduled for later transmission.
*
* Notes from multiple instances of the opcode
* sending to the same output port are collected
* before sending.
*
* The granularity of timing is Csound's kperiod.
*
* Syntax
*
* JackoNoteOut ScsoundPortName, ichannel, ikey, ivelocity
*
* Initialization
*
* ScsoundPortName -- The short name ("portname") of the
* Jack MIDI output port created by jackmidioutconnect.
*
* ichannel -- The MIDI channel (from 0 through 15) to
* receive the note.
*
* ikey -- The MIDI key number (from 0 through 127, 60 is
* middle C) of the note.
*
* ivelocity -- The MIDI velocity number (from 0 through 127)
* of the note.
*
*
* JackoTransport -- Control the Jack transport.
*
* Description
*
* Starts, stops, or repositions the Jack transport.
* This is useful, e.g., for starting an external sequencer
* playing to send MIDI messages to Csound.
*
* Syntax
*
* JackoTransport kcommand, [kposition]
*
* Performance
*
* kcommand -- 0 means "no action", 1 starts the transport,
* 2 stops the transport, and 3 positions the transport
* to kposition seconds.
*
* This opcode can be used at init time or during performance.
*
* The granularity of timing is Csound's kperiod.
*
*
* I M P L E M E N T A T I O N
*
* Processing is done according to the callback model:
*
* 1. The jackinit opcode:
* 1.1. Creates a Jack client,
* which is associated with the
* running instance of Csound.
* 1.2. Registers a JackProcessCallback with Jack.
* 1.3. Registers a SenseEventCallback with Csound.
* 1.4. Installs a MIDI driver callback to consume
* MIDI events coming from Jack input ports.
* 1.5. Puts the Csound processing thread to sleep.
* 1.6. Activates the client.
* 2. The ports are created and connected in the orchestra header.
* 3. After all ports are connected, they are turned on in the
* orchestra header.
* 4. Every time the Jack callback fires:
* 4.1. Any MIDI events pending in the input ports are enqueued
* for dispatch via the MIDI driver callack through
* Csound's normal sensevents mechanism.
* 4.2. csoundPerformKsmps is called.
* 4.3. When the Csound performance is finished:
* 4.3.1. The Csound processing thread is re-awakened.
* 4.3.2. The Jack processing callback is deactivated.
* 4.3.2. The Jack client is closed.
* 5. At the end of processing, the module deinitialization
* function erases all Jack-related state.
*/
--
Michael Gogins
Irreducible Productions
http://www.michael-gogins.com
Michael dot Gogins at gmail dot com
|