Documentation

Documentation of the Multi-region Exporter – for Cubase

Last updated 2017-10-10 for version 1.0.0.2

What and why?

Logo

This tool is made to make the process of exporting multiple audio regions in a Cubase project easier.

If you are exporting a lot of regions (songs, sounds etc.) from the same Cubase project, it can be very cumbersome and time consuming to export them all individually. For every region, you have to select it, open the export menu and give the exported file an appropriate name. Especially if you have to do it more than once – if, for example, you want to change something in the mix – it can be very annoying.

The Multi-region Exporter’s aim is to make this process less annoying, making it easier to iterate and refine along the way.

The principle is very simple: you export the whole project to one audio file and then use this tool to split it into the appropriate and named files on the basis of a Cubase track file.

The splitting/extracting is done by the SoX command line tool which is lossless with uncompressed formats. A big thanks to SoX for sharing their tool openly and freely.

The generation of audio waveform and the optional conversion to mp3 is done by FFMPEG which in turn uses the LAME mp3 encoder for mp3 conversion. Also a big thanks to FFMPEG and LAME for sharing their tools.

I created the tool because I needed it myself for a project where I was working with a lot of foley sounds for a computer game. It is very annoying to export about 30 footstep sounds (including naming them), do some changes and then export them again.
And why not share the tool so that others might benefit from it as well? I think that it makes Cubase a better tool for this kind of projects.

It must be mentioned that the program has been developed and tested with Cubase 8. Therefore I can not guarantee that it will work with all other Cubase versions. Let me know if you experience that the program can’t properly read and interpret the track files from your Cubase version.

It must also be mentioned that Cubase and Steinberg have nothing to do with the development of this tool and therefore they are in no way responsible for it – its functionality / lack of functionality or for supporting it.


Installation

No installation is required. Just place the folder somewhere on your computer – for example where you keep your other programs.

On Windows note that Windows might want to block the program the first time you run it since Windows does not automatically trust it. But you can allow it to run anyway.

On OS X note that first time you open the app,  you should right-click and select “open” – otherwise OS X won’t open it since it comes from an ‘unknown developer’.


User manual

The short version

The Multi-region Exporter – for Cubase (henceforth called the Exporter) works like this:

  1. First, in Cubase, you export a full audio mix-down from time 0:00 containing all desired audio regions. You also export a track file (XML) containing information about the different desired audio regions (start, end, name/description) – this could be from audio tracks or a marker track.
  2. Then you open the Exporter and load the exported audio file and track file. The Exporter can now extract the regions from the audio file and save them to a location of your choice. It can even name the individual files according to names/descriptions you have given the objects in Cubase.

That’s it!

Below is a more in-depth description of how to use the Exporter.

The slightly longer version

The usage of this tool falls in two parts: what is done in Cubase and what is done in the Exporter.
These two parts are described in greater detail below.

In Cubase

What we want to do in Cubase is to export an audio mix-down of the whole project as well as a track file containing info about the different desired audio regions (start, end, name/description).

Exporting an audio mix-down should be straightforward. The only important thing to note here is that you have to export from the beginning of the project. So even if the first audio doesn’t start until 2 minutes in, you have to export from time 0:00. Otherwise, the Exporter will not extract the desired regions at their correct positions in time.

The audio mix-down shown on the left will not work with this tool since it is not exported from the start of the project. The one on the right is the right way :-) The length of the mix-down doesn’t matter as long as it contains all desired regions.

The audio mix-down shown on the left will not work with this tool since it is not exported from the start of the project. The one on the right is, well, right 🙂 The length of the mix-down doesn’t matter as long as it contains all desired regions.

Regarding audio format, you should genrally export to the format you wish to end up with.
The Exporter program can read most uncompressed formats and will extract unmodified bites of audio from the full mix-down file. It uses SoX for this extraction, which is lossless where possible.
As of version 1.0.0.2 the exporter can now also convert the extracted bites to mp3. It uses FFMPEG compiled with LAME to do this. So if you wish to end up with mp3 files, just export to some uncompressed format (wav, aiff, …) in Cubase and let the Exporter program convert to mp3 when outputting.

Now we want to export a Track file from Cubase that contains information about the position and length of each desired region as well as potentially the region’s name. The track file can be based on a marker track with cycle markers or/and on audio tracks containing this information.
If you have an audio track where each audio event corresponds to a desired output region, it is fast and easy to export that track. However, a marker track with cycle markers is more versatile since each marker can span multiple audio events of different length and position.
If you give each event on the track to be exported an appropriate name, this name can be used by the Exporter program for naming the extracted files. You name the individual events in the info line in the field Description (for audio events and markers) or Name (for audio parts).
You export the track(s) by selecting it/them in the project window, then go to File -> Export -> Selected Tracks… If exporting an audio track, make sure to select reference when asked about what to do with the media files – there is no reason to copy them. The resulting track file is an XML file with info about the track(s).

Exporting a track file in Cubase. Here it is done on the basis of a marker track.

Exporting a track file in Cubase. Here it is done on the basis of a marker track.

reference-media-files

Choose ‘reference’ in the pop-up menu (only appears if the export track(s) contains media files). There is no need to copy media files.

Note that you can export multiple tracks in the track file, and that the desired regions can be overlapping if you like.

Tip: If you work with cycle markers I recommend assigning a key command for inserting these. This makes it easy and fast to do. Furthermore, if you really have a lot of regions with similar names, you can handle the naming of events by using the logical editor in Cubase.

In the Multi-region Exporter

What we want to do in the Exporter is to extract the individual desired regions from the full audio mix-down.

First we load the audio mix-down we exported from Cubase.

You load an audio file (audio mix-down from Cubase) by pressing this button and choosing the file.

You load an audio file (audio mix-down from Cubase) by pressing this button and choosing the file.

Then we load the Cubase track file that we also exported from Cubase – it has the file ending .xml. This file contains information about the regions we want to extract from the full-length audio file.

Load the track file by pressing this button.

Load the track file by pressing this button.

Now we should see something like this in the Exporter’s waveform preview area:

The Exporter shows a waveform preview of the loaded audio file as well as a preview of the regions found in the loaded track file.

 

 

 

 

 

 

 

 

Now we are ready to let the Exporter extract the regions and output them to a specified location.

Extract the regions by pressing this button and specifying a location for the output files.

Extract the regions by pressing this button and specifying a location for the output files.

That is basically it! Now the Exporter will have extracted the individual regions from the full audio file and placed the audio files in the folder you specified.

However, there are a couple of very useful settings in the options area that I will quickly explain.

In the file naming settings you can specify whether the extracted files should be named by the names (Description/Name) you have given the corresponding elements in Cubase or whether they should have a fixed name followed by _0001, 0002 etc.

File naming settings

File naming settings

In the trailing time settings you can specify an optional amount of milliseconds to be added to the length of each region. If you have a reverb or delay effect in your mix in Cubase, you would probably want to allow this effect to ring off instead of just cutting abruptly as the ‘content’ of the tracks stops. In such a case it can be useful to add some trailing time. If you use a marker track for exporting the track file, you can of course also just adjust the length of each cycle marker in Cubase.

Trailing time settings

Trailing time settings

In the conversion settings you can choose if the files should be converted to mp3 after being extracted.
You can choose either constant or variable bit rate and also set what that bit rate should be (on average, if variable bit rate is chosen).

Settings for optional conversion to mp3

The conversion is done by FFMPEG compiled with LAME (Lame Ain’t an MP3 Encoder) MP3 encoder.
The LAME algorithm quality is internally set to level 2 which is one better than the default which is level 3. This means that the conversion is not super fast, but the quality should be good. The very best algorithm quality should be level 0 but it is also very slow to encode. Let me know if this is not satisfactory for your needs.


FAQ and troubleshooting

This section is not written yet but it will be updated along the way.


Known issues

No critical issues are known at the moment, but let me know as soon as you find any. They are probably out there…


License, attributions and acknowledgements

The Multi-region Exporter is licensed under the GNU General Public License (GPL) version 3 which basically means that:

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

 

The audio splitting is done by SoX – Sound eXchange which is distributed in binary form with The Multi-region Exporter – for Cubase. SoX itself is licensed under the GNU General Public License version 2. The source code for SoX can be found on the SoX project’s homepage. Below I have included the license notification from the SoX documentation:

Copyright 1998−2013 Chris Bagwell and SoX Contributors.
Copyright 1991 Lance Norskog and Sundry Contributors.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Thanks to SoX for making and sharing this tool.

 

The generation of audio waveform and the optional conversion to mp3 is done by FFMPEG which is distributed with the program in binary form. FFMPEG is itself licensed under the GNU Lesser General Public License (LGPL) version 2.1 or later (read more here: https://www.ffmpeg.org/legal.html).

A big thanks to FFMPEG for creating and sharing their tool.

The distributed OS X binary of FFMPEG is the one available here: https://evermeet.cx/ffmpeg/
You can read more about the included libraries, find source code and their respective licenses on the web site.

The distributed Windows binary of FFMPEG is the one available here: http://ffmpeg.zeranoe.com/builds/
You can read more about the included libraries, find source code and their respective licenses on the web site.

 

FFMPEG in turn uses the LAME mp3 encoder for mp3 conversion. LAME is also open source and also licensed under LGPL. Read more on the LAME website: http://lame.sourceforge.net

Also a big thanks LAME for creating and sharing their tool.

 

The Multi-region Exporter is also distributed with its ‘own’ copy of the Java Runtime Environment (JRE). This is because the Exporter runs on Java – the JRE is included to ensure that the Exporter has access to a compatible JRE version. While this does make the application around 9 times as big as if relying on a public JRE on the user’s computer, I think it is worth the extra megabytes. The included JRE  has its own license agreement, which can be found on Oracle’s JRE download website.

 

Thanks to MegaNørd and GOLD.

Thanks to friends and family for testing and counselling.