BMidiStore

Hérité de: public BMidi

Déclaré dans: be/midi/MidiStore.h

Bibliothèque: libmidi.so

Résumé

La classe BMidiStore met en place un système d'enregistrement et de relecture MIDI. Les messages MIDI reçus pas un objet BMidiStore (en entrée) sont mémorisés en tant qu'évènements (event) dans une liste d'évènements (event list), permettant de rejouer une exécution musicale enregistrée. L'objet peut aussi lire et écrire (ou encore importer et exporter) des fichiers MIDI standards.

Enregistrement

Ce sont les fonctions MIDI Hook de BMidiStore (NoteOn(), NoteOff(), etc...) qui permettent d'enregistrer un morceau MIDI. Lorsqu'un hook MIDI est mis en application, la fonction génère, à partir des arguments qui lui sont transmis, un évènement discret qu'elle ajoute à sa liste. Vous n'avez pas besoin de signifier à un objet BMidiStore de commencer à mémoriser: il peut enregistrer à partir du moment où il a été créé.

Par exemple, pour enregistrer le jeu d'un clavier MIDI externe, associez un objet BMidiStore à un objet BMidiPort et puis lancez ce dernier:

   /* Enregistrement d'un clavier. */
   BMidiStore MyStore;
   BMidiPort MyPort;
   
   MyPort.Open(...);
   MyPort.Connect(MyStore);
   MyPort.Start();
   /* Musique... */

A la fin de l'exécution, demandez l'arrêt de BMidiPort:

   MyPort.Stop();

Signatures temporelles

Les évènements sont ajoutés à la liste d'évènements de BMidiStore dès leur arrivée. Chaque évènement reçoit, lorsqu'il se présente, une signature temporelle (timestamp) dont la valeur est la même que l'argument time transmis à la fonction MIDI Hook par la fonction Spray en amont. Rien ne garantit que les arguments de temps d'évènements MIDI successifs soient classés chronologiquement. Pour s'assurer que les évènements sont correctement ordonnés, appelez la fonction SortEvents() avant de lire la liste (notez que l'écriture de la liste dans un fichier MIDI la trie automatiquement).

Les fonctions d'entrée de BMidiStore ne font pas appel à la fonction SnoozeUntil(): BMidiStore écrit dans sa liste d'évènements consécutivement à la réception d'un nouveau message, sans attendre le moment indiqué par l'argument time.

Effacement et édition d'un enregistrement

Vous ne pouvez pas effacer. Si vous faites une fausse note pendant l'enregistrement (par exemple) et que vous désirez recommencer, vous pouvez simuler un vidage de l'objet ainsi: déconnexion de l'entrée de BMidiStore, suppression de l'objet, création d'une nouvelle instance, et enfin reconnexion.

Editer les évènements dans leur liste est moins qu'impossible (si une telle chose est possible...). Vous ne pouvez ni le faire, ni le simuler, en tous cas pas avec l'implémentation par défaut de BMidiStore. Si vous souhaitez éditer des données MIDI, vous devrez concevoir votre propre classe dérivée de BMidi.

Relecture

Pour "jouer" une liste d'évènements BMidiStore, appelez la fonction Start() de l'objet. Ainsi qu'il est expliqué dans la description de la classe BMidi, Start() met Run() en application. La fonction Run() de BMidiStore lit les évènements selon leur ordre dans la liste d'évènements, et émet les messages appropriés aux objets connectés. Vous pouvez interrompre une lecture de BMidiStore en appelant Stop(). Sinon, l'objet s'arrêtera de lui-même après avoir traité le dernier évènement de sa liste.

La signature temporelle de l'évènement est utilisée comme argument time des fonctions Spray appelées de l'intérieur de la boucle Run(). Avec un bémol toutefois: l'argument time transmis au premier appel à une fonction Spray (pour une exécution) est toujours B_NOW (sur l'utilisation de B_NOW, voyez le paragraphe "Fonctionnement en temps réel" de la classe BMidi). Les arguments time suivants sont recalculés pour conserver un écart correct par rapport au premier évènement. Autrement dit, lorsque vous enclenchez le jeu de BMidiStore, le premier évènement est joué immédiatement, sans tenir compte de la valeur réelle de sa signature temporelle.

Positionnement de l'évènement courant

Vous pouvez indiquer à BMidiStore de commencer à jouer à partir d'un endroit précis de la liste d'évènements en appelant SetCurrentEvent() avant de commencer la lecture. La fonction prend une position dans la liste.

Si vous désirez commencer la lecture à partir d'un moment précis dans la liste d'évènements, il vous faut en premier savoir à quel évènement correspond ce moment. Pour cela, demandez quel évènement arrive à cet instant (exprimé en millièmes de secondes), ou juste après, à la fonction EventAtDelta(). La valeur obtenue sera le bon argument de SetCurrentEvent().

Souvenez-vous que EventAtDelta() renvoie un index du premier évènement à l'instant ou juste après l'instant souhaité. Si vous avez besoin de connaître la position temporelle réelle de l'évènement sélectionné, transmettez son index à la fonction DeltaOfEvent():

   long firstEvent = MyStore->EventAtDelta(3000);
   long actualDelta = MyStore->DeltaOfEvent(firstEvent);

Lecture et écriture de fichiers MIDI

Vous ajouterez des évènements dans une liste d'évènements BMidiStore en lisant, ou en important, un fichier Standard MIDI par l'intermédiaire de la fonction Import(). Il est possible d'importer n'importe quel nombre de fichiers dans le même objet BMidiStore. Après l'import d'un fichier, la liste d'évènements est automatiquement triée.

Une chose à ne pas faire serait d'importer un fichier MIDI dans un objet BMidiStore contenant des évènements précédemment enregistrés à partir de BMidiPort (afin de mixer le fichier et l'enregistrement). Ni de faire le travail inverse: vous ne pouvez pas importer un fichier et ensuite enregistrer à partir de BMidiPort. Les valeurs temporelles utilisées dans un fichier sont incompatibles avec celles générées pour les évènements reçus de BMidiPort: le résultat ne serait certainement pas satisfaisant.

Pour sauvegarder la liste d'évènements sous la forme d'un fichier MIDI, utilisez la fonction Export() de BMidiStore.

Constructeur et Destructeur

BMidiStore() , ~BMidiStore()

	BMidiStore(void) virtual ~BMidiStore()

Le constructeur crée un nouvel objet BMidiStore vide. Le destructeur supprime l'objet et ce qu'il a mémorisé.

Fonctions membres

BeginTime()

	uint32 BeginTime(void) const

Retourne le moment, en ticks, où la dernière exécution a débuté. Cette fonction n'est valable que si l'objet a effectivement joué.

CountEvents() , SortEvents() , DeltaOfEvent() , EventAtDelta()

	uint32 CountEvents(void) const void SortEvents(bool force = false) uint32 DeltaOfEvent(uint32 index) const uint32 EventAtDelta(uint32 delta) const

CountEvents() retourne le nombre d'évènements de la liste.

SortEvents() trie chronologiquement les évènements de la liste. L'objet mémorise (prudemment) la qualité du tri de ses évènements: si l'argument force a la valeur false et que l'objet ne considère pas l'opération nécessaire, le tri ne sera pas effectué. Si force est à true, l'opération est toujours effectuée, sans souci de sa pertinence.

DeltaOfEvent() renvoie le "delta time" de l'évènement index de la liste d'évènements. Le delta time d'un évènement est l'intervalle de temps (exprimé en millièmes de secondes) entre le premier évènement de la liste et lui-même.

EventAtDelta() donne la position de l'évènement qui se produit à (ou après) delta millièmes de secondes à partir du début de la liste.

CurrentEvent() voir SetCurrentEvent()

DeltaOfEvent() voir CountEvents()

Export() , Import()

	status_t Export(const entry_ref *to_file, int32 format) status_t Import(const entry_ref *from_file)

Export() trie chronologiquement la liste d'évènements de l'objet, pour l'écrire ensuite sous forme de fichier MIDI standard selon le format indiqué. L'argument format devrait être soit 0 ou 1. Le fichier to_file doit être déjà créé, et n'est pas vidé avant écriture.

Import() lit le fichier MIDI standard à partir du fichier désigné et en ajoute les évènements à la liste d'évènements de l'objet.

VALEURS DE RETOUR

• B_OK. Le fichier a été correctement lu ou écrit.

• B_NO_MEMORY Ne peut allouer suffisamment de mémoire pour recevoir le fichier (concerne uniquement la fonction Import()).

• POSIX errors. Une autre erreur de fichier a empêché l'opération.

SetCurrentEvent() , CurrentEvent()

	void SetCurrentEvent(uint32 index) uint32 CurrentEvent(void)

SetCurrentEvent() positionne l'évènement courant (le prochain évènement traité par l'objet) sur l'évènement index de la liste.

CurrentEvent() renvoie la position du prochain évènement traité.

SetTempo() , Tempo()

	void SetTempo(int32 beatsPerMinute) int32 Tempo(void) const

Détermine et retourne le tempo (la vitesse d'exécution des évènements) de l'objet, en beats per minute. Le tempo par défaut est de 60 bpm.

SortEvents voir CountEvents()