It’s the large recent work that Stefan Westerfeld (who btw finally decided to start his own blog) has put into shaping up the remaining bits of bsewavetool (man page draft).
This is a very handy tool, that’ll finally be installed for public consumption in the upcoming release (it has been developed in SVN since 2004!). It can clip/normalize/ogg-encode/highpass/lowpass/upsample/downsample/etc chunks from the BSE multi sample files, and is normally used for shell-scripting the construction of sample kits from an unsorted pile of raw unprocessed sample data (note to self: blog some example use cases after the release).

Another addition are interesting new instruments by Krzysztof Foltman.

Oh – and before i forget, the synthesis link section on the website got some new updates as well: Beast Synthesis Links,

Also, Stefan pointed me at a YouTube video of Beast the other day:

The video is very nicely done, but it has the usual YouTubeish low quality artefacts.

Hanno Behrens had been fairly active in pushing the Beast project before the last release. In particular he has been stirring up the mailing list with feature requests. One of the things we managed to get in in response to these efforts is a list of commonly used musical tuning systems. Besides the already supported 12-TET which is the 12 note per octave equal temperament used in all western contemporary music, this includes further TET variants, Indian tuning, pentatonic tunings, meantone tunings and various well tempered tunings mostly intended for organs.

Hanno also published a very well written C64-retrospective article about Beast synthesis in the 20th Issue (german) of the Lotek64 Magazine. And additionally, the technical backgrounds for this article are described in the Beast wiki: SID Vicious (english).

In particular, we’ve been hacking on the unit tests and tried to get make check invocations run much faster. To paraphrase Michael C. Feathers from his very interesting book Working Effectively with Legacy Code on unit tests:

Unit tests should run fast – a test taking 1/10th of a second is a slow unit test.

Most tests we had executed during make check took much longer. Beast has some pretty sophisticated test features nowadays, i.e. it can render BSE files to WAV files offline (in a test harness), extract certain audio features from the WAV files and compare those against saved feature sets. In other places, we’re using tests that loop through all possible input/output values of a function in brute force manner and assert correctness over the full value range. Adding up to that, we have performance tests that may repeatedly call the same functions (often thousands or millions of times) in order to measure their performance and print out measurements.

These kind of tests are nice to have for broad correctness testing, especially around release time. However we did run into the problem of make check being less likely executed before commits, because running the tests would be too slow to bother with. That of course somewhat defeats the purpose of having a test harness. Another problem that we ran into were the intermixing of correctness/accuracy tests with performance benchmarks. These often sit in the same test program or even the same function and are hard to spot that way in the full output of a check run.

To solve the outlined problems, we changed the Beast tests as follows:

* All makefiles support the (recursive) rules: check, slowcheck, perf, report (this is easily implemented by including a common makefile).

* Tests added to TESTS are run as part of check (automake standard).

* Tests added to SLOWTESTS are run as part of slowcheck with --test-slow.

* Tests added to PERFTESTS are run as part of perf with --test-perf.

* make report runs all of check, slowcheck and perf and captures the output into a file report.out.

* We use special test initialization functions (e.g. sfi_init_test(argc,argv)) which do argument parsing to handle --test-slow and --test-perf.

* Performance measurements are always reported by the treport_maximized(perf_testname,amount,unit) function or the treport_minimized() variant thereof, depending on whether the measured quantity is desired to be maximized or minimized. These functions are defined in birnettests.h and print out quantities with a magic prefix that allows grepping for performance results.

* make distcheck enforces a successful run of make report.

Together, these changes have allowed us to easily tweak our tests to have faster test loops (if !test_slow) and to conditionalize lengthy performance loops (if test_perf). So make check is pleasingly fast now, while make slowcheck still runs all the brute force and lengthy tests we’ve come up with. Performance results are now available at the tip of:

	$ make report
	[...]
	$ grep '^#TBENCH=' report.out
	#TBENCH=mini:         Direct-AutoLocker:      +83.57            nSeconds
	#TBENCH=mini:         Birnet-AutoLocker:     +104.574           nSeconds
	#TBENCH=maxi:  CPU Resampling FPU-Up08M:     +260.4562325006    Streams
	#TBENCH=maxi:  CPU Resampling FPU-Up16M:     +184.19598452754   Streams
	#TBENCH=maxi:  CPU Resampling SSE-Up08M:     +399.04229848364   Streams
	#TBENCH=maxi:  CPU Resampling SSE-Up16M:     +338.5240352065    Streams 

The results are tailored to be parsable by performance statistics scripts. So writing scripts to present performance report differences and to compare performance reports between releases is now on the TODO list. ;-)

Beast-0.7.0 NEWS
beast-0.7.0.tar.bz2

We really hope people are going to have fun with this release and report all bugs they encounter in Bugzilla.

In response to my last blog entry on this topic, one commenter wrote:

I think that starting another documentation project would be totally useless.

I don’t think i can agree here. For any software solvable problem you have, you can only write your own tool if you don’t find an existing one that covers your needs or could be extended to do so. Admittedly, i didn’t know about Synopsis back then, and i intend to investigate more of its innards at some point to figure whether it can be integrated with Doxer nicely. Until then, Beast does again have a working documentation tool, re-enabling us to keep documenting the source code and updating the website.
At this point, the CVS version of Beast has been fully migrated to generate and display HTML runtime documentation, using a browser according to the users preferences. Also all source code documentation was converted and the website is fully generated from Doxer. All of this is driven by circa 6k lines of code, made possible only by the expressiveness of Python and by using Doxygen as a source code parsing backend.

a) We need to generate reference documentation from C and C++ source code comments.
b) Since we also need to process ordinary documentation files (say an FAQ) that involve lots of text and occasionally graphics, Tex-info syntax is to be preferred over XML-style markup (well – actually *anything* is preferable over XML-style markup for lots of human digestible text) if at all possible.
c) We need to generate documentation from introspection tools (e.g. bseautodoc.c spews out documentation for object properties, signals and channels).
d) The source code comments should use the same markup style that is used for ordinary documentation and design documents (e.g. the Beast FAQ or the Beast Quick Start Guide).
e) We need to be able to generate decently looking HTML for the Beast website.
f) We need to be able to generate manual pages – nothing too sophisticated, covering roughly the feature set of man(7) on Linux is more than sufficient.
g) We need a runtime documentation format with support for “live documentation”, this was one of the reasons to go with GtkTextView in the original documentation. Basically “live” here means, runtime documentation displayed by a running Beast instance, e.g. triggered from the “Help” menu, should be able to provide links/buttons/activators that can trigger the running Beast instance to play back documentation example songs.
h) Taking (b) to the extreme, writing documentation should be as easy as possible, maybe even as easy as writing documentation with OpenOffice Writer and exporting it as HTML. Of course, this would conflict with (g)… or – would it?
i) Automatic external cross-linking should be supported, e.g. to all the documentation sections offered at http://developer.gnome.org/doc/API/. Especially within the reference documentation, automatic link markup would be good to have, without authors having to dig up links or add markup to the relevant keywords.
j) The tool-chain required to build documentation should be available from a reasonably standard system, such as the current Debian stable.
k) Something similar to the custom macro definition feature of Tex-info as described in The Beast Documentation Quest (1) should be offered by the new documentation system as well if at all possible.

The above requirements at hand, i looked around quite a bit to find a documentation tool that would allow me to fulfil all or most of them.
It turned out that (a) and (g) definitely were amongst the harder ones, while (i) was mostly solved already by the old documentation system with regards to link indexing. There, we used a Perl script to extract various kind of (source code identifier, developer.gnome.org/doc/API/-link) tuples from developer.gnome.org. This scrip even covered enum values, something that gtk-doc does not generate own index lists for.
One of the next things i was to find out, was that many tools don’t deliver HTML output as nice as that generated by gtk-doc. But then, even the very long-term plans for gtk-doc do not include extension towards C++ parsing…
In general, C++ parsing isn’t one of the tasks easily covered. As far as i could figure, there is no decent free C++ parser (including comments) usable for documentation purposes other than Doxygen. Luckily, Doxygen is a reasonably standard tool (j) and also supports ‘@’-style markup that looks Tex-info alike (b) and generates documentation in multiple output formats (amongst them HTML and manual pages). Unfortunately i could not get the Doxygen HTML output to look anywhere close as decent as gtk-doc generated HTML pages. That included attempts at sophisticated CSS modifications and even hacking it’s documentation generation abilities. At closer inspection, Doxygen also did not fully fit what i had in mind for a general purpose documentation tool to cover, i.e. (b), (c) and (k). It should be noted however that Doxygen supports link index imports in a Doxygen specific format that can be used to enable automatic external linking (i) with some effort.