Q2Q

Launching Q2Q 1.0.0

2024-06-20T00:00:00-06:00

Lights… Places… GO Cue 1!

We are beyond excited to announce the official launch of Q2Q™, a next generation sound cueing software for live performance for both macOS and Windows. As we state on our website, “Q2Q™ is the tool for creating professional sound designs from Windows or MacOS devices!…Enjoy the flexibility of designing wherever and whenever you want” …but really this launch means so much more than that. For us, this represents a move in the theatre industry towards making art more accessible. This is the first professional program available for both Mac and PC. Q2Q 1.0 is available now. With a purchase of Version 1, all future minor version updates (Q2Q 1.x) will be available free of charge. Subsequent major versions (i.e. Q2Q 2.0) will be available at a reduced upgrade price.

With the goal of availability in mind, we have priced this product with our users in mind. We offer a variety of discounts. The full Version 1 product is available for a $249 “buy it now” price. Coming soon, we will be implementing a “rent-to-own” price which includes a daily fee for the periods of time the product is being used. And all payments made while renting will count towards the full purchase price. Once that amount is reached, the product license will be owned in full by the user.

With this being the first official release of Q2Q, we wanted to provide some resources to help users. If you are just getting started, there are tutorials here. For more advanced use cases, we have created a user manual here. For other updates and to get more connected please follow our socials! We are GoQ2Q on Facebook, GoQ2Q on Instagram, Go_Q2Q on X (Formerly known as Twitter), https://goq2q.net/blog/ for our blog, and https://goq2q.net for our website. There is also a Reddit community at r/goq2q. If you want to see more from John Wostenberg, Q2Q founder, and his team at Wosterware, please follow along with our journey. These resources will be a guide for users as well as a window into the behind the scenes (literally) of the development and progress.

As a program and group that is still growing and learning in an industry that is forever evolving, we want to continue to improve and change as the artists who create change. With this focus, we encourage any and all feedback. Please provide feedback directly to our team at info@goq2q.net and on social media! We are dedicated to building a cross platform program that will not remain stagnant. Feedback from you, our users, is vital to ensure the continued evolution of this program. We are always open for notes.

Thank you all for the support. We hope this program will allow for the creation of art that inspires.

- The Q2Q Team

Automatic cue naming

2022-04-30T00:00:00-06:00

Starting with version 0.6.0, Q2Q will automatically name cues for you now! This was a very fun feature to implement, and there’s a lot of customization you can leverage.

By default, new projects will have their cues named with a single alphabetical letter, starting at the beginning–A. Adding and deleting cues will follow this rule. This is because these new cues are actually all named $ - which Q2Q substitutes with a letter, one greater than the previous. So when you add a new cue, it doesn’t change the other cues’ names; it just affects how Q2Q interprets the names. You can see this for yourself by opening your .q2q file in a text editor and seeing that all the cues really are named $!

But some people don’t want letters; they want numbers. Got you covered there, too–use # for your cue names (you can set a project-default cue name in the top toolbar), and it will auto-increment starting from 0.

There’s a lot more to this cue-naming grammar however; this is where it starts to get interesting. You can add multiples of a substitution symbol to get Q2Q to count with more digits: for example $$$, $$$, $$$ becomes AAA, BBB, CCC; and ###, ###, ### becomes 000, 001, 002. Q2Q can increment more than one at a time if you add a number to the end of the substitution, like so: ###5, ###5, ###5 becomes 000, 005, 010 (works similarly with letters). There’s still more stuff you can do–for the full spec, take a look at the Automatic Cue Naming chapter in the user guide.

My preferred naming strategy

When designing a show, I prefer sounds to be named with letters, and lights with numbers, so there’s less ambiguity, letting the stage manager call out “Ready 30BD… GO!” (meaning “light cue 30 and sound cue BD”). If you use numbers for both, the SM has to specify which are which (unless you’re doing a Chicago-style one-operator-to-rule-them-all show, in which case, you have no need of this distinction).

I also like my cues spaced out, so I have the flexibility to add stuff in between last-minute without causing a rename of half the show and pissing off the SM.

So I would usually go with the $$5 naming scheme (or perhaps $$$5 if I really need the deep organization, like for shows with many cues per scene). I usually use the first letter correspond to the scene, and the second letter is incrementing inside the scene. Say we have Scene 1, Scene 2, Scene 3, each with 3 sound cues inside them. I would name my cues like so:

$$5 -> AA
$$5 -> AF
$$5 -> AK
{BA} -> BA
$$5 -> BF
$$5 -> BK
{CA} -> CA
$$5 -> AF
$$5 -> AK

During the design phase, it’s very easy to just insert cues here and there. But, after the cues have been taken down by the SM, and therefore shouldn’t change names anymore, we can start “locking down” things as we insert new cues. For example, say we need to add two cues between AF and AK without affecting the existing names. We can just give each intermediate cue its desired name without curly braces, and Q2Q will ignore it when counting:

$$5 -> AA
$$5 -> AF
AH -> AH
AJ -> AJ
$$5 -> AK
{BA} -> BA
$$5 -> BF
…etc

This feature also pairs well with the cuesheet CSV export, which uses cue names as displayed by Q2Q, as expected!

I’m excited to see what people do with this feature. What naming scheme will YOU choose?

I reinvented the wheel last week, and here’s why

2021-10-26T00:00:00-06:00

Common wisdom tells you that many problems worth solving have already been solved for you (probably more than once), and that you should leverage this fact. In other words: don’t reinvent the wheel; stand on the shoulders of giants. I very often follow this rule of thumb. But last week, I broke that rule and wrote an F# implementation of the OSC (Open Sound Control) protocol¹.

But first, what is OSC? Here’s a quick and incomplete overview (there’s plenty of information elsewhere on the intertubes): OSC is a simple but very flexible message format, used to allow devices or applications to talk to each other in ad-hoc and arbitrary ways. An OSC message consists of an address string, such as "/oscillators/1/frequency", and a list of arguments (which can be things like strings, integers, floats, etc). An OSC client sends messages to a server, which will attempt to dispatch the message based on the functionality it decides to expose. OSC also has pattern matching, which allows, for example, "/oscillators/*/frequency" to simultaneously dispatch to "/oscillators/1/frequency", "oscillators/2/frequency", "oscillators/foobar/frequency", etc. It is quite powerful and flexible, and lots of things speak OSC. The spec defines simple encodings for these messages². It was originally intended for use in music- and audio-based applications (such as synthesizers) as a potential alternative to MIDI, but has enjoyed wider multimedia applicability in things like lighting, animatronics, and robotics (to name a few).

Q2Q support for OSC (both sending a receiving) is the latest feature I’ve been working on, and it’s been a rabbit hole, but boy, has it been a fun rabbit hole. Since Q2Q is written in F#, I was looking for ways to send/receive OSC messages in the language. Though F# has a strong open-source community, it’s not too surprising that nobody has published a first-class OSC library. There are C# OSC libraries (such as SharpOsc), but I didn’t consider them an option because I knew I really wanted all the goodies that well-designed F#-oriented code awards you, such as immutability, making illegal states unrepresentable, and railway-oriented programming (ROP), algebraic data types—the list goes on. So I decided to reinvent the wheel and build an OSC library in F#. Besides, this was a wheel I wanted to learn about.

The specs for OSC 1.0 and OSC 1.1 are pretty short as far as specs go; only a couple pages each—you could read them over lunch. This makes it pretty straightforward to just drive out the whole implementation using TDD (Test Drive Development). The entire OSC 1.1 AST (excluding bundles and timetags, which I just didn’t get around to) consists of the following:

type OscAtom =
    | OscInt32 of intValue:int32
    | OscFloat32 of floatValue:float32
    | OscString of stringValue:string
    | OscBlob of blobData:byte[]
    | OscBool of bool
    | OscNone
    | OscImpulse
type OscMessage = { addressPattern: string; arguments: OscAtom list }

Boom, Domain Designed.

Next step: Implementing each of the encoding/decoding functions for the atoms and messages, according to the spec. After that: the message dispatching / matching logic (which F# is particularly good at). Then, finally: the code that fires these messages over the wire (I wrote both UDP and TCP clients), as well as the code that can listen for OSC messages coming in from the network (UDP only for now). The whole thing is just shy of 600 lines of code. Sure, I could have spent that time doing other Q2Q features. But in this case, the advantages outweigh the time spent: this implementation will fit right in with the rest of Q2Q’s idiomatic F# codebase, and I know for a fact that it is correct to the spec³ since it has complete test coverage. There’s almost 2x the lines of test code than actual code. Sometimes that could be a code smell, but I would argue that it’s not when you’re implementing a protocol from its spec.

Do I always recommend reinventing the wheel? Definitely not. Would I recommend trying it from time to time? Absolutely.

Coming soon to theaters near you: OSC support in Q2Q 0.5.0! In the mean time, for geeks like me, you can browse the source code, or use the NuGet package.

Um, ackshually, it’s a content format, not a protocol… Yes, I know, dear reader, and they spell this out in the OSC 1.1 spec. I called it that for sake of simplicity. Calling it a “content format” may be more correct, but I think “protocol” gives a better connotation in that opening paragraph. You may notice that I more correctly use the “content format” description later on. Whatever, go ahead and crucify me for that if you’re feeling particularly pedantic today. I’ll still love you. You—yes, you, beloved reader. ↩
There’s also bundles, which I don’t get into this post. You can read more about those elsewhere. ↩
Well, as long as the messages coming in are well-formed. It doesn’t have particularly good handling of error cases for now, but I can always circle back later. The client also doesn’t do a particularly good job of sanitizing the messages before they’re sent (i.e. preventing you from using an address without a slash at the beginning). ↩

Using ASCII waveforms to test real-time audio code

2021-10-12T00:00:00-06:00

I draw sound wave ASCII art in Q2Q’s source code. These ASCII art waveforms ensure that the real-time audio engine at the heart of Q2Q stays bug-free.

Software development best-practices dictate that if you want your software to be high-quality (who doesn’t?), you test your code, you test it automatically, and you test it often (as part of a continuous integration build process). In other words, you should make accidentally publishing bugs as difficult as possible. Q2Q, of course, has test suites to prevent regressions, and a CI system that makes sure all tests pass (just like any other good software project).

Q2Q is a real-time audo application. It does things like starting/stopping sounds, fading/panning sounds, and looping/devamping sounds, and these kinds of features are mission-critical. They cannot fail or have bugs. Here’s the catch: audio programming is extremely tricky to get right. When I was first writing Q2Q, I spent days trying to get anything coherent out of the speakers even at all. It’s very easy to get some buffer index wrong, or do a time conversion incorrectly, or forget to handle more than just mono and stereo signals, or even to just be off by a small number of samples without noticing.

This is hard to write automated tests for – how are you supposed to write a test that asserts, “a one-second fade-out should work”? My initial thought was to take a sliding average (approximating loudness), and assert that it constantly decreases, for example. But then how would you test looping functionality? Or mixing different sounds together? Or crossfading? Trying to come up with how to test those invariants is very hard.

I stumbled across a post from Jane Street’s tech blog that describes a technique for testing hardware oscillators (which generate waveforms), where they render the oscillator’s output to text, which can be very easilly diffed. Additionally, the F# compiler has some tests (which it calls “baseline tests”) that test the new compiler’s output against output from an earlier known-good version of itself. A combination of these two approaches sounded very good to me.

Q2Q employs this ASCII-waveform baseline testing technique to great success. Every time I work on a new feature, I manually create some test cases for the new feature. For example, if I were writing the component that performs fading and panning, I would first create a test case to exercise a simple fade (perhaps a short fade-out), and output to a simple array, instead of an actual output device (this is pretty easy as I use NAudio for audio processing). Then, I would attempt to implement the feature. Then, I would use my ASCIIWaveformRenderer to turn the output into an array of strings, acting as a visual representation of the data that would have been outputted to the audio device. I would run this in F# interactive, so that if it looks good, I can copy-paste the result right back into the test code as the baseline to compare against from now on. If it didn’t look right, I would tweak the code until it does. Rinse and repeat for all the corner cases.

Fade-in baseline test using an ASCII waveform.

A baseline test for a looping using slices. Notice how the slicer first plays straight through a signal, then loops the last part of the waveform.

This provides a great regression testing experience. Recently, while implementing pan laws, I noticed that the CI had started failing. I opened up the error log and was greeted with this:

ASCII waveform baseline test failure.

This is telling us that a test is failing because the system’s output did not match the expected ASCII waveform baseline.

The tests for FadeSampleProvider (the component that handles fading and panning), were catching a legitimate mistake. As you can see, storing the baseline as an ASCII waveform makes this much easier to debug than if it were to be an opaque array of raw sample data. Expecto, the test framework I use, even gives a good enough visual diff there. You can kind of tell what is going wrong just by the picture – it’s supposed to be a fade out, as indicated by the first (green) waveform (so gradually decreasing in overall volume), and it kind of does this at first, but then the signal starts fading back in! Why was this happening? After some digging, it turns out that I had accidentally removed the clamping logic in the interpolation functions, thinking they were do-nothing code. These interpolations are simply mathematical functions¹, so you can put in numbers you would consider invalid, and they will happily start doing funny things – like causing a fade-out to start fading back in. Oops!

The interesting thing is that if these tests weren’t around, this bug probably would have gone unidentified, causing subtle glitches, for quite a while. Since the audio is streamed in real time, it is not processed all at once; rather, it is processed in buffered chunks. When the audio device is ready for more sound to play, it gives Q2Q an empty buffer, which Q2Q then fills with samples from the processing chain. This happens many time per second (as determined by the size of the buffer). FadeSampleProvider only calls the interpolation function when a fade is actually in progress – but it only re-decides this on the next buffer. Therefore, when a fade ends before the end of the buffer (which it likely would), it would exhibit this problem for the rest of that audio buffer. Buffer sizes are small enough (as measure in seconds) that it likely would have sounded like a millisecond-long click or pop, which would have been extremely difficult to attribute to the FadeSampleProvider in particular. I would have probably chalked it up to slow file reading, or inefficient code causing the device to drop some frames.

ASCII-waveform baseline tests are great, but what about the cases I don’t know to write tests for? Can we take this even further? Check back for a future blog post – Property-based fuzz testing to the rescue!

EDIT: since people were interested, I’ve posted the waveform-to-ASCII renderer as a snippet free to use: http://www.fssnip.net/85g

I use different kinds of interpolation functions to implement the different fade shapes you can use, such as linear fades, constant-power fades, and compromise fades. Here’s a sample graph of some of these functions plotted together, and here’s that same graph without restricting the x axis to a specific range. Observe that the output makes sense as a fade volume for x values from 0 to 1, but start to get weird outside of that range. Hence, we need to clamp the x value between 0 and 1 before we pass it into the interpolation formula. ↩