Prev Next Table of Contents

14.5. Implementing a StereoEffect

After you know how server-side object creation works, what stereo effects are, and how you can get them running, it would be a nice idea to actually do this in an example. Next, let's write something similar to Example_ADD that works like a StereoEffect.

First, what should it do? I thought it may be useful to emulate the standard options you have for balance at every amplifier: keep stereo as it is, keep left channel only, keep right channel only, reverse channels, and downmix stereo.

14.5.1. IDL Again

First, you need a representation for these states. That is done best using an enumeration value. So you get the following:

   1 
   2 #include <artsflow.idl>
   3 enum StereoBalanceState { sbThrough, sbLeftOnly,
   4               sbRightOnly, sbReverse, sbDownMix };
   5 

Then, you need to make the interface derive from StereoEffect. Thus, no streams need to be declared at all because StereoEffect already does this. The interface looks as simple as this:

   1 
   2 interface StereoBalanceControl : Arts::StereoEffect {
   3     attribute StereoBalanceState balance;
   4 };
   5 

That's all. Put it into a file balance.idl and invoke mcopidl:

   1 
   2 $ mcopidl -I$KDEDIR/include/arts balance.idl
   3 

14.5.2. The Code

Now to the implementation. First to the attribute stuff; these are mapped, as I mentioned previously, to two functions: one that changes the value and one that queries it. They are both called balance. One gets a parameter to set a new value, and one returns the old value. You should also have an internal variable to store the current state (it's called _balance here), and initialize this properly in the C++ constructor. Up to now, you have the following:

   1 
   2 #include "balance.h"
   3 #include <stdsynthmodule.h>
   4 
   5 using namespace Arts;
   6 
   7 class StereoBalanceControl_impl : public
   8     StereoBalanceControl_skel, StdSynthModule
   9 {
  10 private:
  11     StereoBalanceState _balance;
  12 public:
  13     StereoBalanceControl_impl() : _balance(sbThrough) {}
  14     StereoBalanceState balance()    { return _balance; }
  15     void balance(StereoBalanceState b) { _balance = b; }
  16 

The method that is still missing is calculateBlock. The most important thing to watch here is that the volume doesn't change through our balance control. That means, for downmix (mixing the left and right stereo channels to mono output), you shouldn't simply add everything, but divide by two. The other cases shouldn't be hard to handle. Here is the rest of the code, then, while you are left with some cases to write, too:

   1 
   2     void calculateBlock(unsigned long samples)
   3 {
   4         unsigned long i;
   5         switch (_balance) {
   6             case sbThrough:
   7                 for(i=0;i<samples;i++)
   8                 {
   9                     outleft[i] = inleft[i];
  10                     outright[i] = inright[i];
  11                 }
  12                 break;
  13             case sbDownMix:
  14                 for(i=0;i<samples;i++)
  15                 {
  16                     float mix = (inleft[i]+inright[i])/2;
  17                     outleft[i] = mix;
  18                     outright[i] = mix;
  19                 }
  20                 break;
  21             /* exercise : implement the other cases */
  22         };
  23     }
  24 };
  25 REGISTER_IMPLEMENTATION(StereoBalanceControl_impl);
  26 

14.5.3. Using the Effect

Because you want to be able to load and use the effect inside the server, put it into a library that can be dynamically loaded. To do so, you'll also create a class definition called StereoBalanceControl.mcopclass, with the following content:

   1 
   2 Library=libstereobalancecontrol.la
   3 

Because making is a bit difficult, the following is a makefile again, for making the whole module:

   1 
   2 LIBDIR=$(KDEDIR)/lib
   3 CXX=libtool --mode=compile g++
   4 CXXFLAGS=-I$(KDEDIR)/include/arts
   5 LD=libtool --mode=link g++
   6 LDFLAGS=-module -rpath $(LIBDIR) -L$(LIBDIR) -lartsflow \
   7                      -lartsflow_idl -lmcop -ldl
   8 CP=libtool --mode=install cp
   9 TARGET=libstereobalancecontrol.la
  10 OBJS=balance.lo balance_impl.lo
  11 
  12 all: $(TARGET)
  13 
  14 install: $(TARGET)
  15     $(CP) $(TARGET) $(LIBDIR)
  16     $(CP) StereoBalanceControl.mcopclass $(LIBDIR)
  17 
  18 libstereobalancecontrol.la: $(OBJS)
  19     $(LD) -o $(TARGET) $(LDFLAGS) $(OBJS)
  20 
  21 balance_impl.lo: balance_impl.cc
  22     $(CXX) $(CXXFLAGS) -c balance_impl.cc
  23 
  24 balance.lo: balance.cc
  25     $(CXX) $(CXXFLAGS) -c balance.cc
  26 
  27 balance.cc: balance.idl
  28     mcopidl $(CXXFLAGS) balance.idl
  29 

Thus, compilation and installation are simply done with

   1 
   2 $ make
   3 $ make install
   4 

although you may need to do the last as root (that is, su root -c 'make install'). Okay, now you have installed an effect, which should be dynamically loadable into the server. To try it out, Listing 14.4 is a test program:

Example 14.4. Running StereoBalanceControl on the Server

   1 
   2  1: #include "balance.h"
   3  2: #include <soundserver.h>
   4  3: #include <stdio.h>
   5  4:
   6  5: using namespace Arts;
   7  6:
   8  7: void fail(char *why) { printf("%s\n",why); exit(1); }
   9  8:
  10  9: int main(int argc, char **argv)
  11  10: {
  12 11:     if(argc != 2) fail("use two arguments");
  13 12:
  14 13:     Dispatcher dispatcher;
  15 14:     SimpleSoundServer server(Reference("global:Arts_SimpleSoundServer"));
  16 15:     if(server.isNull()) fail("can't connect server");
  17 16:
  18 17:     StereoBalanceControl bcontrol;
  19 18:     bcontrol = DynamicCast(server.createObject("StereoBalanceControl"));
  20 19:     if(bcontrol.isNull()) fail("can't create object");
  21 20:
  22 21:     if(strcmp(argv[1],"downmix") == 0)
  23 22:         bcontrol.balance(sbDownMix);
  24 23:     if(strcmp(argv[1],"through") == 0)
  25 24:         bcontrol.balance(sbThrough);
  26 25:     /* add the others possibilities, if you like */
  27 26:     bcontrol.start();
  28 27:
  29 28:     StereoEffectStack effectstack = server.outstack();
  30 29:     long id=effectstack.insertBottom(bcontrol,"Balance");
  31 30:     printf("type return to quit\n"); getchar();
  32 31:     effectstack.remove(id);
  33 32:     return 0;
  34 33: }
  35 

Finally, to get that running, do the following: First compile

   1 
   2 $ g++ -o setbalance setbalance.cc  -I$KDEDIR/include/arts
   3 -L$KDEDIR/lib -lsoundserver_idl -lartsflow -lartsflow_idl
   4 -lstereobalancecontrol -lmcop -ldl
   5 

That is everything in one line. Then call ldconfig as root (to get your freshly installed library registered):

   1 
   2 $ su root -c 'ldconfig'
   3 

Make sure that something is running on the soundserver (for instance, listen to an MP3 or .wav), and then type

   1 
   2 $ setbalance downmix
   3 

That should downmix the stuff that is played. As you can see, running objects server side is really easy through MCOP. Imagine what the overhead would be like if you needed to transfer all data from the server to the setbalance program, which would do the calculations, and you had to transfer everything back again.

Prev Next Table of Contents