summaryrefslogtreecommitdiffstats
path: root/arts/midi/artsmidi.idl
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commite2de64d6f1beb9e492daf5b886e19933c1fa41dd (patch)
tree9047cf9e6b5c43878d5bf82660adae77ceee097a /arts/midi/artsmidi.idl
downloadtdemultimedia-e2de64d6f1beb9e492daf5b886e19933c1fa41dd.tar.gz
tdemultimedia-e2de64d6f1beb9e492daf5b886e19933c1fa41dd.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'arts/midi/artsmidi.idl')
-rw-r--r--arts/midi/artsmidi.idl379
1 files changed, 379 insertions, 0 deletions
diff --git a/arts/midi/artsmidi.idl b/arts/midi/artsmidi.idl
new file mode 100644
index 00000000..63bf868b
--- /dev/null
+++ b/arts/midi/artsmidi.idl
@@ -0,0 +1,379 @@
+ /*
+
+ Copyright (C) 2000 Stefan Westerfeld
+ stefan@space.twc.de
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+
+ */
+
+/*
+ * DISCLAIMER: The interfaces in artsmidi.idl (and the derived .cc/.h files)
+ * DO NOT GUARANTEE BINARY COMPATIBILITY YET.
+ *
+ * They are intended for developers. You shouldn't expect that applications in
+ * binary form will be fully compatibile with further releases of these
+ * interfaces.
+ */
+
+#include <artsflow.idl>
+
+module Arts {
+
+/* This is modelled somewhat after
+ - the AudioManager concept
+ - the aRts-0.3.4.1 MidiPort concept
+ - libkmid
+
+ It adds timing as new feature compared to older implementation, and also
+ tries to do the full set of midi operations.
+
+ It's current state is "experimental", and "binary compatibility not kept".
+ */
+
+/**
+ * an absolute timestamp
+ */
+struct TimeStamp {
+ long sec,usec;
+};
+
+/**
+ * different status of a midi command
+ */
+enum MidiCommandStatus {
+// Masks:
+ mcsCommandMask = 0xf0,
+ mcsChannelMask = 0x0f,
+
+// Commands:
+ mcsNoteOff = 0x80,
+ mcsNoteOn = 0x90,
+ mcsKeyPressure = 0xa0,
+ mcsParameter = 0xb0,
+ mcsProgram = 0xc0,
+ mcsChannelPressure = 0xd0,
+ mcsPitchWheel = 0xe0
+};
+
+/**
+ * the following are to be used once status is (mcsParameter|channel):
+ */
+enum MidiCommandParameter {
+ mcpSustain = 0x40,
+ mcpAllNotesOff = 0x7b
+};
+
+/**
+ * a midi command
+ */
+struct MidiCommand {
+ byte status;
+ byte data1;
+ byte data2;
+};
+
+/**
+ * a midi event
+ */
+
+struct MidiEvent {
+ TimeStamp time;
+ MidiCommand command;
+};
+
+/**
+ * a midi port
+ */
+interface MidiPort {
+ /**
+ * the current absolute time (since the existence of the midi device)
+ */
+ readonly attribute TimeStamp time;
+
+ /**
+ * the current play time
+ *
+ * Some midi devices, for instance synthetic audio devices, have a certain
+ * amount of internal buffering. This causes a time difference between
+ * where events are currently being rendered, which is the timestamp
+ * obtained by "time", and the events that the listener is hearing right
+ * now, which is this timestamp, the "playTime".
+ */
+ readonly attribute TimeStamp playTime;
+
+ /**
+ * processes a midi command
+ */
+ oneway void processCommand(MidiCommand command);
+
+ /**
+ * processes a midi event
+ */
+ oneway void processEvent(MidiEvent event);
+};
+
+enum MidiClientDirection { mcdPlay, mcdRecord };
+enum MidiClientType { mctDestination, mctApplication };
+
+/**
+ * information about a midi client
+ */
+struct MidiClientInfo {
+ long ID;
+ sequence<long> connections;
+
+ MidiClientDirection direction;
+ MidiClientType type;
+ string title, autoRestoreID;
+};
+
+/**
+ * a midi manager client
+ */
+interface MidiClient {
+ readonly attribute MidiClientInfo info;
+
+ /**
+ * you can change the title of your client on the fly - everything else
+ * (besides the actual assignment) is static
+ */
+ attribute string title;
+
+ /**
+ * creates a new port through which the client can receive data from
+ * the midi manager
+ */
+ void addInputPort(MidiPort port);
+
+ /**
+ * creates a new port through which the client can send data to the
+ * midi manager
+ */
+ MidiPort addOutputPort();
+
+ /**
+ * removes a port
+ */
+ void removePort(MidiPort port);
+};
+
+interface AudioSync;
+
+/**
+ * this synchronizes multiple midi clients - it also allows synchronization
+ * with audio events
+ */
+interface MidiSyncGroup {
+ /**
+ * adds a midi client to the synchronization group
+ *
+ * hint: during adding the client, the timestamps related to that
+ * client will jump
+ */
+ void addClient(MidiClient client);
+
+ /**
+ * deletes a midi client from the synchronization group
+ */
+ void removeClient(MidiClient client);
+
+ /**
+ * adds an AudioSync object to the synchronization group
+ *
+ * hint: during adding the AudioSync object, the timestamps related to
+ * that object might jump
+ */
+ void addAudioSync(AudioSync audioSync);
+
+ /**
+ * deletes an AudioSync object from the synchronization group
+ */
+ void removeAudioSync(AudioSync audioSync);
+};
+
+/**
+ * Some general notes to the understanding of the midi manager. The midi
+ * manager has the task to intelligently assign applications to destinations.
+ *
+ * It is important to understand what it actually does to understand the
+ * distinction first, which is expressed through the "MidiClientType" of
+ * each client.
+ *
+ * APPLICATIONS: An application is a user visible application, that produces
+ * or records midi data. It is important for the understanding of an
+ * application, that an application actually *wants* to be supplied with
+ * data, or wants to get its data played. Thus, adding an application to
+ * the midi manager is an implicit request: "go and find a place where to
+ * put the events to (or get the events from)".
+ *
+ * Examples for applications would be games or midi players.
+ *
+ * DESTINATIONS: A destination is a system service that plays or supplies
+ * midi data. The characteristic here is that a destination is something
+ * that is there if you need it.
+ *
+ * Examples for destinations might be might be a hardware device or an
+ * emulation of a hardware device (such as a virtual sampler).
+ *
+ * So the process is as follows:
+ * - destinations register themselves at the midi manager, and provide
+ * system services in that way
+ *
+ * - when the user starts an application (such as a midi player), the midi
+ * manager's task is to assign it to a suitable destination
+ *
+ * - the user can interact with the process by changing the way applications
+ * are assigned to destinations - the midi manager will try to learn
+ * what the user wants, and next time do a better job while assigning
+ *
+ * To actually record or play some data, you need to register a client first,
+ * and after that, you can add Input or Output "MidiPort"s to your client,
+ * so that you can actually send or receive events with them.
+ */
+interface MidiManager { // SINGLETON: Arts_MidiManager
+ /**
+ * a list of clients
+ */
+ readonly attribute sequence<MidiClientInfo> clients;
+
+ /**
+ * add a client
+ *
+ * this creates a new MidiManagerClient
+ */
+ MidiClient addClient(MidiClientDirection direction, MidiClientType type,
+ string title, string autoRestoreID);
+
+ /**
+ * connect two clients
+ */
+ void connect(long clientID, long destinationID);
+
+ /**
+ * disconnect two clients
+ */
+ void disconnect(long clientID, long destinationID);
+
+ /**
+ * add a synchronization group
+ *
+ * this creates a new MidiSyncGroup
+ */
+ MidiSyncGroup addSyncGroup();
+};
+
+interface MidiTest : MidiPort {
+};
+
+interface RawMidiPort : MidiPort {
+ attribute string device;
+ attribute boolean input, output;
+ attribute boolean running;
+ boolean open();
+};
+
+interface AlsaMidiGateway {
+ boolean rescan();
+};
+
+interface AlsaMidiPort : MidiPort {
+ attribute long client;
+ attribute long port;
+ boolean open();
+};
+
+/**
+ * EXPERIMENTAL interface for audio synchronization - this allows multiple
+ * objects to be started and stopped at a precisely defined timestamp
+ */
+interface AudioSync {
+ /**
+ * the current time
+ */
+ readonly attribute TimeStamp time;
+
+ /**
+ * the current play time
+ *
+ * Since aRts has internal buffering, there is a time difference between
+ * where events are currently being rendered, which is the timestamp
+ * obtained by "time", and the events that the listener is hearing right
+ * now, which is this timestamp, the "playTime".
+ */
+ readonly attribute TimeStamp playTime;
+
+ /**
+ * queues calling synthModule.start() later
+ *
+ * (will keep a reference on the module until executed)
+ */
+ void queueStart(SynthModule synthModule);
+
+ /**
+ * queues calling synthModule.stop() later
+ *
+ * (will keep a reference on the module until executed)
+ */
+ void queueStop(SynthModule synthModule);
+
+ /**
+ * atomically executes all queued modification to the flow system
+ */
+ void execute();
+
+ /**
+ * atomically executes all queued modifications to the flow system
+ * at a given time
+ */
+ void executeAt(TimeStamp timeStamp);
+};
+
+/**
+ * Midi Timer - can be used to provide timing for midi ports that have
+ * no "native" timing.
+ */
+interface MidiTimer
+{
+ /**
+ * the current time
+ */
+ readonly attribute TimeStamp time;
+
+ /**
+ * this will put the event into an event queue and send it to the port
+ * once the time for the event has been reached
+ */
+ oneway void queueEvent(MidiPort port, MidiEvent event);
+};
+
+/**
+ * Uses the system time (i.e. gettimeofday() and similar) to provide midi
+ * timing
+ */
+interface SystemMidiTimer : MidiTimer
+{
+};
+
+/**
+ * Uses the audio time (i.e. samples rendered to /dev/dsp) to provide midi
+ * timing
+ */
+interface AudioMidiTimer : MidiTimer
+{
+};
+
+};