Imported Upstream version 4.2-build2006upstream/4.2-build2006upstream

1 files changed, 651 insertions, 0 deletions

diff --git a/tutorials/sndkit/softsynth/softsynth.c b/tutorials/sndkit/softsynth/softsynth.c
new file mode 100644
index 0000000..12e77eb
--- /dev/null
+++ b/tutorials/sndkit/softsynth/softsynth.c
@@ -0,0 +1,651 @@
+/*
+ * Purpose: A simple software MIDI synthesizer program.
+ * Copyright (C) 4Front Technologies, 2002-2004. Released in public domain.
+ *
+ * Description:
+ * This is a pretty simple program that demonstrates how to do MIDI input at
+ * the same time with audio playback (using select). It also demonstrates how
+ * to use the MIDI loopback devices of OSS 4.0 (and later). 
+ * Please note that this program is nothing but a programming example. It's
+ * "output quality" equals to $10 (or cheaper) toy organs. However it's very
+ * amazing how great some songs (MIDI files) sound even 90% of the MIDI 
+ * information is simply ignored.
+ *
+ * What this program actually does is that it listen's to the MIDI input port
+ * and interprets the incoming MIDI stream (using the midiparser routines
+ * included in the OSSlib library).
+ *
+ * For simplicity reasons this program does nothing else but plays simple
+ * sine waves at the right note frequencies. Percussive sounds (MIDI
+ * channel 10) are simply ignored because playing them as sine waves doesn't
+ * make any sense. All MIDI controllers, pitch bend as well as all the other
+ * MIDI features are ignored too. However the all notes off control change
+ * message is handled because otherwise hanging notes will be left if the
+ * client (player) application gets killed abnormally.
+ *
+ * There is simple fixed envelope handling (actually just attack and decay)
+ * and primitive handling of note on velocity. These features appeared to be
+ * necessary because otherwise nobody can listen the output.
+ *
+ * This program is not too usefull as a synthesizer. It's not intended to be
+ * any super "modular synthesizer". However it demonstrates how simple it is
+ * to implement any kind of software MIDI synthesizer using the OSS API.
+ * You don't need to know how to use some 450 audio related calls or 300
+ * MIDI/sequencer related calls. As you will see practically everything will
+ * be handled automagically by OSS. So you can spend all your time on
+ * writing the application itself. This program was written, and debugged
+ * in less than 5 hours from scratch (including MIDI input, audio output
+ * and the actual synthesis). In fact it took longer time to write these
+ * comments than the application itself.
+ *
+ * The major benefit of this super simple design is that it cannot fail. 
+ * Provided that you don't try to set the buffer size to a too small value
+ * the application logic is fully nuke proof. It will work unmodified with
+ * every sound card in the world (past, current and future).
+ *
+ * The MIDI parser code was taken from some earlier work but we have included
+ * if in the OSSlib library for you (under LGPL). Please feel free to use it
+ * in your own OSS MIDI applications.
+ *
+ * To use this program you will need to install the "4Front MIDI loopback"
+ * driver using the "Add new card/device" function of soundconf.
+ * Then start this program in background (the audio and MIDI device names
+ * can be given as command line arguments. For example
+ *
+ *	softsynth /dev/dsp /dev/midi01
+ *
+ * You can find out the loopback MIDI device number by looking for the
+ * "MIDI loopback server side" devices using the {!xlink ossinfo} -m
+ * command. Btw, nothing prevents using any "real" physical MIDI port as the
+ * input.
+ *
+ * When the synthesizer server is running you can play any MIDI file using
+ * some OSS based MIDI sequencer/player such as {!xlink ossmplay}.
+ */
+#include <stdio.h>
+#include <unistd.h>
+#include <stdlib.h>
+#include <string.h>
+#include <fcntl.h>
+#include <math.h>
+#include <sys/select.h>
+#include <sys/soundcard.h>
+#include <midiparser.h>
+midiparser_common_t *parser = NULL;
+
+int audio_fd;
+int midi_fd;
+int sample_rate = 48000;
+
+/*
+ * The open_audio_device routine opens the audio device and initializes it 
+ * for the required mode. This code was borrowed directly from the
+ * {!nlink singen.c} sample program. However since the buffer size
+ * is inportant with this kind of application we have added a call that
+ * sets the fragment and buffer sizes.
+ */
+
+static int
+open_audio_device (char *name, int mode)
+{
+  int tmp, fd;
+
+  if ((fd = open (name, mode, 0)) == -1)
+    {
+      perror (name);
+      exit (-1);
+    }
+
+/*
+ * Setup the audio buffering policy so that reasonably small latencies 
+ * can be obtained.
+ *
+ * 4 fragments of 256 samples (512 bytes) might be good. 256 samples
+ * will give timing granularity of 256/sample_rate seconds (5.33 msec)
+ * which is fairly adequate. The effect of the granularity (fragment size) in
+ * this type of applications is timing jitter (or choking). Every event that
+ * occurs withing the 5.33 msec period (fragment time) will get executed
+ * in the beginning of the next period. If the fragment size is decreased
+ * then the granularity will decrease too. However this will cause slight
+ * increase in the CPU consumption of the application.
+ *
+ * The total buffer size (number_of_fragments*fragment_time) will define the
+ * maximum latency between the event (note on/off) and the actual change in the
+ * audio output. The average latency will be something like
+ * (number_of_fragments-0.5)*fragment_time). The theoretical average latency
+ * caused by this application is (4-0.5)*5.33 msec = ~19 msec). 
+ * 
+ * In musical terms 5.33 msec granularity equals to 1/750 note at 60 bpm
+ * and 19 msecs equals to 1/214. This should be pretty adequate.
+ *
+ * The latency can be decreased by limiting the number of fragments and/or the
+ * fragment size. However the after the buffer size drops close to the
+ * capabilities of the system (delays caused by the other applications) the
+ * audio output will start breaking. This can cured only by tuning the
+ * hardware and the software environments (tuning some kernel parameters and
+ * by killing all the other applications). However this is in no way an OSS
+ * issue.
+ *
+ * With these parameters it was possible to compile Linux kernel in another
+ * terminal window without any hiccup (fairly entry level 2.4 GHz P4 system
+ * running Linux 2.6.x).
+ */
+  tmp = 0x00040009;
+  if (ioctl (fd, SNDCTL_DSP_SETFRAGMENT, &tmp) == -1)
+    {
+      perror ("SNDCTL_DSP_SETFRAGMENT");
+    }
+
+/*
+ * Setup the device. Note that it's important to set the
+ * sample format, number of channels and sample rate exactly in this order.
+ * Some devices depend on the order.
+ */
+
+/*
+ * Set the sample format
+ */
+  tmp = AFMT_S16_NE;		/* Native 16 bits */
+  if (ioctl (fd, SNDCTL_DSP_SETFMT, &tmp) == -1)
+    {
+      perror ("SNDCTL_DSP_SETFMT");
+      exit (-1);
+    }
+
+  if (tmp != AFMT_S16_NE)
+    {
+      fprintf (stderr,
+	       "The device doesn't support the 16 bit sample format.\n");
+      exit (-1);
+    }
+
+/*
+ * Set the number of channels (mono)
+ */
+  tmp = 1;
+  if (ioctl (fd, SNDCTL_DSP_CHANNELS, &tmp) == -1)
+    {
+      perror ("SNDCTL_DSP_CHANNELS");
+      exit (-1);
+    }
+
+  if (tmp != 1)
+    {
+      fprintf (stderr, "The device doesn't support mono mode.\n");
+      exit (-1);
+    }
+
+/*
+ * Set the sample rate
+ */
+  sample_rate = 48000;
+  if (ioctl (fd, SNDCTL_DSP_SPEED, &sample_rate) == -1)
+    {
+      perror ("SNDCTL_DSP_SPEED");
+      exit (-1);
+    }
+
+/*
+ * No need for rate checking because we will automatically adjust the
+ * signal based on the actual sample rate. However most application must
+ * check the value of sample_rate and compare it to the requested rate.
+ *
+ * Small differences between the rates (10% or less) are normal and the
+ * applications should usually tolerate them. However larger differences may
+ * cause annoying pitch problems (Mickey Mouse).
+ */
+
+  return fd;
+}
+
+static int
+open_midi_device (char *name, int mode)
+{
+  int tmp, fd;
+
+/*
+ * This is pretty much all we nbeed.
+ */
+
+  if ((fd = open (name, mode, 0)) == -1)
+    {
+      perror (name);
+      exit (-1);
+    }
+
+  return fd;
+}
+
+#define MAX_VOICES 256
+
+typedef struct
+{
+  int active;			/* ON/OFF */
+  int chn, note, velocity;	/* MIDI note parameters */
+
+  float phase, step;		/* Sine frequency generator */
+
+  float volume;			/* Note volume */
+
+  float envelope, envelopestep;	/* Envelope generator */
+  int envelopedir;		/* 0=fixed level, 1=attack, -1=decay */
+} voice_t;
+
+static voice_t voices[MAX_VOICES] = { 0 };
+
+static int
+note_to_freq (int note_num)
+{
+
+/*
+ * This routine converts a midi note to a frequency (multiplied by 1000)
+ * Notice! This routine was copied from the OSS sequencer code.
+ */
+
+  int note, octave, note_freq;
+  static int notes[] = {
+    261632, 277189, 293671, 311132, 329632, 349232,
+    369998, 391998, 415306, 440000, 466162, 493880
+  };
+
+#define BASE_OCTAVE	5
+
+  octave = note_num / 12;
+  note = note_num % 12;
+
+  note_freq = notes[note];
+
+  if (octave < BASE_OCTAVE)
+    note_freq >>= (BASE_OCTAVE - octave);
+  else if (octave > BASE_OCTAVE)
+    note_freq <<= (octave - BASE_OCTAVE);
+
+  return note_freq;
+}
+
+/*
+ * The note_on() routine initializes a voice with the right
+ * frequency, volume and envelope parameters.
+ */
+
+static void
+note_on (int ch, int note, int velocity)
+{
+  int i;
+
+  for (i = 0; i < MAX_VOICES; i++)
+    if (!voices[i].active)
+      {
+	voice_t *v = &voices[i];
+	int freq;
+	float step;
+
+/*
+ * Record the MIDI note on message parameters (just in case)
+ */
+
+	v->chn = ch;
+	v->note = note;
+	v->velocity = velocity;
+
+/*
+ * Convert the note number to the actual frequency (multiplied by 1000).
+ * Then compute the step to be added to the phase angle to get the right
+ * frequency.
+ */
+
+	freq = note_to_freq (note);
+	step = 1000.0 * (float) sample_rate / (float) freq;	/* Samples/cycle */
+	v->step = 2.0 * M_PI / step;
+	if (v->step > M_PI)	/* Nyqvist was here */
+	  return;
+	v->phase = 0.0;
+
+/*
+ * Compute the note volume based on the velocity. Use linear scale which
+ * maps velocity=0 to the 25% volume level. Proper synthesizers will use more
+ * advanced methods (such as logarithmic scales) but this is good for our 
+ * purposes.
+ */
+	v->volume = 0.25 + ((float) velocity / 127.0) * 0.75;
+
+/*
+ * Initialize the envelope engine to start from zero level and to add
+ * some fixed amount to the envelope level after each sample.
+ */
+	v->envelope = 0.0;
+	v->envelopedir = 1;
+	v->envelopestep = 0.01;
+
+/*
+ * Fire the voice. However nothing will happen before the next audio
+ * period (fragment) gets computed. This means that all the voices started
+ * during the ending period will be rounded to start at the same moment.
+ */
+	v->active = 1;
+	break;
+      }
+}
+
+/*
+ * The note_off() routine finds all the voices that have matching channel and
+ * note numbers. Then it starts the envelope decay phase (10 times slower
+ * than the attack phase.
+ */
+
+static void
+note_off (int ch, int note, int velocity)
+{
+  int i;
+
+  for (i = 0; i < MAX_VOICES; i++)
+    if (voices[i].active && voices[i].chn == ch)
+      if (voices[i].note = note)
+	{
+	  voice_t *v = &voices[i];
+	  v->envelopedir = -1;
+	  v->envelopestep = -0.001;
+	}
+}
+
+/*
+ * all_notes_off() is a version of note_off() that checks only the channel
+ * number. Used for the All Notes Off MIDI controller (123).
+ */
+
+static void
+all_notes_off (int ch)
+{
+  int i;
+
+  for (i = 0; i < MAX_VOICES; i++)
+    if (voices[i].active && voices[i].chn == ch)
+      {
+	voice_t *v = &voices[i];
+	v->envelopedir = -1;
+	v->envelopestep = -0.01;
+      }
+}
+
+/*
+ * Compute voice computes few samples (nloops) and sums them to the
+ * buffer (that contains the sum of all previously computed voices).
+ *
+ * In real world applications it may be necessary to convert this routine to 
+ * use floating point buffers (-1.0 to 1.0 range) and do the conversion
+ * to fixed point only in the final output stage. Another change you may
+ * want to do is using multiple output buffers (for stereo or multiple
+ * channels) instead of the current mono scheme.
+ *
+ * For clarity reasons we have not done that.
+ */
+
+static void
+compute_voice (voice_t * v, short *buf, int nloops)
+{
+  int i;
+
+  for (i = 0; i < nloops; i++)
+    {
+      float val;
+
+/*
+ * First compute the sine wave (-1.0 to 1.0) and scale it to the right
+ * level. Finally sum the sample with the earlier voices in the buffer.
+ */
+      val = sin (v->phase) * 1024.0 * v->envelope * v->volume;
+      buf[i] += (short) val;
+
+/*
+ * Increase the phase angle for the next sample.
+ */
+      v->phase += v->step;
+
+/*
+ * Handle envelope attack or decay
+ */
+      switch (v->envelopedir)
+	{
+	case 1:
+	  v->envelope += v->envelopestep;
+	  if (v->envelope >= 1.0)	/* Full level ? */
+	    {
+	      v->envelope = 1.0;
+	      v->envelopestep = 0.0;
+	      v->envelopedir = 0;
+	    }
+	  break;
+
+	case -1:
+	  v->envelope += v->envelopestep;
+	  if (v->envelope <= 0.0)	/* Decay done */
+	    {
+	      v->envelope = 0.0;
+	      v->envelopestep = 0.0;
+	      v->envelopedir = 0;
+	      v->active = 0;	/* Shut up */
+	    }
+	  break;
+	}
+    }
+}
+
+/*
+ * The midi_callback() function is called by the midi parser library when
+ * a complete MIDI message is seen in the input. The MIDI message number
+ * (lowest 4 bits usually set to zero), the channel (0-15), as well as the
+ * remaining bytes will be passed in the parameters.
+ *
+ * The MIDI parser library will handle oddities (like running status
+ * or use of note on with velocity of 0 as note off) so the application
+ * doesn't need to care about such nasty things.
+ *
+ * Note that the MIDI percussion channel 10 (9 as passed in the ch parameter)
+ * will be ignored. All other MIDI messages other than note on, note off
+ * and the "all notes off" controller are simply ignored. 
+ *
+ * Macros like MIDI_NOTEON and MIDI_NOTEOFF are defined in soundcard.h.
+ */
+
+static void
+midi_callback (void *context, int category, unsigned char msg,
+	       unsigned char ch, unsigned char *parms, int len)
+{
+  switch (msg)
+    {
+    case MIDI_NOTEON:
+      if (ch != 9)		/* Avoid percussions */
+	note_on (ch, parms[0], parms[1]);
+      break;
+
+    case MIDI_NOTEOFF:
+      if (ch != 9)		/* Avoid percussions */
+	note_off (ch, parms[0], parms[1]);
+      break;
+
+    case MIDI_CTL_CHANGE:
+      if (parms[0] == 123)
+	all_notes_off (ch);
+      break;
+
+    }
+}
+
+/*
+ * The handle_midi_input() routine reads all the MIDI input bytes
+ * that have been received by OSS since the last read. Note that 
+ * this read will not block.
+ *
+ * Finally the received buffer is sent to the midi parser library which in turn
+ * calls midi_callback (see above) to handle the actual events.
+ */
+
+static void
+handle_midi_input (void)
+{
+  unsigned char buffer[256];
+  int l, i;
+
+  if ((l = read (midi_fd, buffer, sizeof (buffer))) == -1)
+    {
+      perror ("MIDI read");
+      exit (-1);
+    }
+
+  if (l > 0)
+    midiparser_input_buf (parser, buffer, l);
+}
+
+/*
+ * handle_audio_output() computes a new block of audio and writes it to the
+ * audio device. As you see there is no checking for blocking or available
+ * buffer space because it's simply not necessary with OSS 4.0 any more.
+ * If there is any blocking then the time below our "tolerances".
+ */
+
+static void
+handle_audio_output (void)
+{
+/*
+ * Ideally the buffer size equals to the fragment size (in samples).
+ * Using different sizes is not a big mistake but the granularity is 
+ * defined by the buffer size or the fragment size (depending on which
+ * one is larger),
+ */
+  short buf[256];
+  int i;
+
+  memset (buf, 0, sizeof (buf));
+
+  /* Loop all the active voices */
+  for (i = 0; i < MAX_VOICES; i++)
+    if (voices[i].active)
+      compute_voice (&voices[i], buf, sizeof (buf) / sizeof (*buf));
+
+  if (write (audio_fd, buf, sizeof (buf)) == -1)
+    {
+      perror ("Audio write");
+      exit (-1);
+    }
+}
+
+int
+main (int argc, char *argv[])
+{
+  fd_set readfds, writefds;
+/*
+ * Use /dev/dsp as the default device because the system administrator
+ * may select the device using the {!xlink ossctl} program or some other
+ * methods
+ */
+  char *audiodev_name;
+  char *mididev_name;
+
+/*
+ * It's recommended to provide some method for selecting some other
+ * device than the default. We use command line argument but in some cases
+ * an environment variable or some configuration file setting may be better.
+ */
+  if (argc != 3)
+    {
+      fprintf (stderr, "Usage: %s audio_device midi_device\n", argv[0]);
+      exit (-1);
+    }
+
+  audiodev_name = argv[1];
+  mididev_name = argv[2];
+
+/*
+ * It's mandatory to use O_WRONLY in programs that do only playback. Other
+ * modes may cause increased resource (memory) usage in the driver. It may
+ * also prevent other applications from using the same device for 
+ * recording at the same time.
+ */
+  audio_fd = open_audio_device (audiodev_name, O_WRONLY);
+
+/*
+ * Open the MIDI device for read access (only).
+ */
+
+  midi_fd = open_midi_device (mididev_name, O_RDONLY);
+
+/*
+ * Init the MIDI input parser (from OSSlib)
+ */
+
+  if ((parser = midiparser_create (midi_callback, NULL)) == NULL)
+    {
+      fprintf (stderr, "Creating a MIDI parser failed\n");
+      exit (-1);
+    }
+
+/*
+ * Then the select loop. This program uses select instead of poll. However 
+ * you can use select if you like (it should not matter).
+ *
+ * The logic is very simple. Wait for MIDI input and audio output events.
+ * If there is any MIDI input then handle it (by modifying the voices[]
+ * array.
+ *
+ * When there is space to write more audio data then we simply compute one
+ * block of output and write it to the device.
+ */
+
+  while (1)			/* Infinite loop */
+    {
+      int i, n;
+
+      FD_ZERO (&readfds);
+      FD_ZERO (&writefds);
+
+      FD_SET (audio_fd, &writefds);
+      FD_SET (midi_fd, &readfds);
+
+      if ((n = select (midi_fd + 1, &readfds, &writefds, NULL, NULL)) == -1)
+	{
+	  perror ("select");
+	  exit (-1);
+	}
+
+      if (n > 0)
+	{
+	  if (FD_ISSET (midi_fd, &readfds))
+	    handle_midi_input ();
+	  if (FD_ISSET (audio_fd, &writefds))
+	    handle_audio_output ();
+	}
+    }
+
+/*
+ * You may wonder what do we do between the songs. The answer is nothing.
+ * The note off messages (or the all notes off controller) takes care of
+ * shutting up the voices. When there are no voices playing the application
+ * will just output silent audio (until it's killed). So there is no need to
+ * know if a song has ended.
+ *
+ * However the MIDI loopback devices will retgurn a MIDI stop (0xfc) message
+ * when the client side is closed and a MIDI start (0xfa) message when some
+ * application starts playing. The server side application (synth) can
+ * use these events for it's purposes.
+ */
+
+/*
+ * That's all folks!
+ *
+ * This is pretty much all of it. This program can be easily improced by
+ * using some more advanced synthesis algorithm (wave table, sample playback,
+ * physical modelling or whatever else) and by interpreting all the MIDI
+ * messages. You can also add a nice GUI. You have complete freedom to
+ * modify this program and distribute it as your own work (under GPL, BSD
+ * proprietary or whatever license you can imagine) but only AS LONG AS YOU
+ * DON*T DO ANY STUPID CHANGES THAT BREAK THE RELIABILITY AND ROBUSTNESS.
+ *
+ * The point is that regardless of what you do there is no need to touch the
+ * audio/MIDI device related parts. They are already "state of the art".
+ * So you can spend all your time to work on the "payload" code. What you
+ * can do is changing the compute_voice() and midi_callback() routines and
+ * everything called by them.
+ */
+
+  exit (0);
+}