Questions about arts (mostly to be used in docs)

[David Bishop]

On Monday 24 February 2003 07:48 am, Stefan Westerfeld wrote:
> artsplay is the wrong thing to try out PlayObjects. It is hardcoded to use
> Arts::Synth_PLAY_WAV, since these files are cacheable (PlayObjects are
> not). Use kaboodle.

For some reason I thought artsplay would just generically play anything arts 
could handle.  Now, with your suggestion, I've managed to crash both kaboodle 
and arts, for the very first time!  That's actually more along the lines of 
what I was expecting (first attempt going right? hah!).

> Arts::Refiller has methods to configure the format. I added documentation
> to resample.h in the CVS now, please ask me if that documentation is not
> good enough ;).

Looks wonderful.  As I dig into it more, I may indeed have a follow-up, though 
:)

> > 2b)  The same method takes an argument of type 'unsigned long' (len).
> > What does that represent? The length of time/bytes/blocks/frames that
> > you should read into 2a's buffer? Something else entirely?  If it is a
> > length, how do you know what unit it is in?
>
> Bytes. See newly added documentation.

If you keep adding stuff to the headers, my documentation efforts will be 
unneeded, unwanted, and useless!  What a relief that would be....

> You need to implement calculateBlock, basically. But since most decoders

The only thing we need to do now is add some documentation for calculateBlock 
:-)  I presume you mean the one defined in object.h?

Ok, this is becoming clearer.  Thanks for what's you've gotten so far!

Next round:

Does a larger number in the "Preference" field in a .mcopclass file mean it is 
"more" prefered, or less?

Does arts use the KDEDIRS variable, such that you could install "third-party" 
playobjects in /usr/local and have kde proper in /usr, like you can with 
apps?

I'm attaching a *very* rough draft of the stuff I'm been coming up with. Bits 
of it will turn into a true FAQ, others bits are just random notes to be used 
in some (planned) examples, and possibly a HOWTO-CODE.txt file (code 
conventions, etc).  I'm really just looking to make sure that I don't lead 
anyone astray...  

-- 
"Yousa steala precious from meesa!" - Jar-Jaromir

D.A.Bishop
-------------- next part --------------
<Coding Style>

Please use .cc when adding stuff to arts directly.
FIXME identation used? find parameters to indent to replicate

<Compilation Issues>

Q: What libraries do I link against to make a PlayObject?

A: kmedia2_idl, soundserver_idl and artsflow

<General>

Q: What would a good example of a PlayObject be?

A: <TEMP> Checkout the sources for the audiofile_artsplugin. FIXME Create a decent example


Q: What does the "preference" mean in the mcopclass file?

A: This determines which PlayObject to use for a certain type of file. FIXME The higher the number, the
more "prefered" the PlayObject is?

Q: I've got a "rough draft" of my PlayObject. How can I test it?

A: Run 'make install' as root (NEEDED!), and then launch kaboodle.  If your files do not show up in the
'Open File' dialog, then they have not been properly registered via your .mcopclass file. Go
back and doublecheck that it is not only properly formatted (with no typos!), but is also put
into the right directory.  You should be able to compare against other .mcopclass files installed
already.  Once they are recognized, try and play one.  More than likely, artsd and/or kaboodle 
will crash at this point. On to debugging!  If it works perfectly the first time, I officially 
hate you.

Q: I want to create a PlayObject.  What is the bare minimum that I need to do?

A: 
* make an IDL file, and define a new interface (i.e. FooPlayObject)
	<http://www.arts-project.org/doc/handbook/interfaces.html>
* derive from the skeleton in your implementation
	<FooPlayObjectI seems to be a convention>
* to make it easier, consider deriving from Arts::StdSynthModule
	<This is easier as it implements various functions for you (start, stop, etc)>
* implement all virtual methods that the compiler tells you to reimplement
	<There are a lot of these, be prepared to compile/check/fix/repeat a lot>

You need to implement calculateBlock, basically. But since most decoders
provide data as 16bit integer in some fixed sampling rate, PlayObjects usually
need to use some form of conversion. There are three commonly used:

1. resample.h: Arts::Resampler, Arts::Refiller
2. convert.h: uni_convert_stereo_2float
3. http://www.mega-nerd.com/SRC/ (libsamplerate)

The first is easier to use (of the two that ship with arts). Someone will 
need to write somewhat more perfect resampling code, that supplies the 
features of both (for instance, convert.h can also resample _to_ 16bit data, 
not only _from_). However for now, choose what is more convenient for you, 
or implement your own resampling.

Q: I want to use threading in my PlayObject.  Is there a standard way to do that?

A: While it is not an official part of kde-multimedia, several playobjects are now using itc
(available at http://www.derkarl.org/itc/).  Itc was written by Charles Samuels, author of
several other arts-based projects, including noatun.