Onda 3.5 : Manual

Table of contents

1  Introduction

[ Table of contents ]

Onda is a Java application that compresses 16-bit and 24-bit AIFF and WAVE audio files with the Onda lossless audio compression (LAC) algorithm. The Onda algorithm doesn't perform as well as some other open-source LAC algorithms in terms of either speed or compression ratio; its virtue, if it can be said to have one, is that it is easy to understand and to implement, involving no mathematics beyond a bit of arithmetic.

Onda is distributed under version 3 of the GNU General Public License; for details, see the file license.txt that is included in the Onda distribution.

Onda has the following features:

• It can compress 16-bit and 24-bit AIFF and WAVE audio files, and validate and expand files that it has compressed.
• It can be used as a command-line (console) application or with a graphical user interface (GUI).
• It can operate on single files or on all the files in a directory, with optional recursion. Input files and directories can be specified directly or as a list of pathnames in a text file.
• When it is run as a GUI application, input files and directories can be selected by dragging and dropping on systems that support the operation.
• It can preserve the ancillary chunks of AIFF and WAVE files (eg, the bext chunk used in BWF files), using a filter to specify the chunks that should be included in or excluded from a compressed file.

The website of the Onda project is at http://onda.sourceforge.net/ .

2  Requirements

[ Table of contents ]

Onda is a Java application that requires a Java runtime environment that supports Java SE 7 (Java 1.7), such as Oracle's Java Runtime Environment (JRE), version 7 or later.

3  Contents of the distribution

[ Table of contents ]

The following files are included in the distribution:

4  Installing and running Onda

[ Table of contents ]

Onda consists of a single JAR (executable Java archive) file, onda.jar and a configuration file, onda-config.xml, which contains user preferences. The use of the configuration file is optional but recommended. The application can be installed in two ways: with the OndaInstaller program or by copying files from the .zip or .tar.gz archive of the Onda executable distribution.

4.1  Executing a JAR file

Both the Onda application and the installer are executable JAR (Java archive) files that require a Java runtime environment, which includes a program named java for running JAR files — a Java launcher. When you install a Java runtime environment, it may create an association on your system between JAR files and its Java launcher. (Oracle's Java runtime environment on Windows associates JAR files with an additional Java launcher named javaw that runs without a console window.) If so, or if you have created the association yourself, you will be able to run a JAR file directly (eg, by double-clicking on an icon of the JAR file in a file manager). If not, you can run a JAR file by invoking the java launcher tool from a command line and supplying the location of the JAR file as an argument. There are examples below of command lines for running the JAR file of the Onda application under Linux/UNIX and Windows.

4.2  Installing Onda

4.2.1  Installation with the installer program

The installer is an executable JAR (Java archive) file that requires the same Java runtime environment as the Onda application itself. It can be run directly or indirectly in the ways described above.

In the opening display of the installer, you can choose the components that you want to install and the directories in which they will be installed. It is recommended that you install the configuration file in its default directory; the default directories of the other components should also be suitable for most users. If you install the executable file and the configuration file, a file named onda-properties.xml will be generated and written to the same directory as the executable file to inform the Onda application of the location of the configuration file. This file is required only if the configuration file was not installed in the default directory.

Any existing file that has the same name as an installed file will be overwritten without warning except for a configuration file, whose properties will be preserved if they conflict with the properties of the new file.

The final display of the installer has a Show files command that displays a list of files that were installed. If the installation was successful, you may wish to keep a list of the files so that you will know where to find them when you uninstall Onda, which does not have an automated means of uninstallation. If the installation failed, you may wish to remove any files that were installed.

4.2.2  Direct installation

The direct installation of Onda consists simply of copying the JAR file and, optionally, the default configuration file to suitable locations on your system. If the configuration file is not installed in its default directory, you will need to inform the Onda application of the location of the configuration file, which can be done either on the command line or in a properties file.

4.3  Console mode and GUI mode

The Onda application can be run in two modes, referred to in this document as console mode and GUI mode. The main operations (compress, expand and validate) are available in both modes.

Onda decides on its mode — whether to run as a console application or as a GUI application — when it starts up: if the application has command-line arguments, it will run as a console application unless one of the arguments specifies a GUI; otherwise, it will run with a GUI. The command-line arguments that determine the mode are the arguments to the Onda application, not the options for the java launcher. (The application's arguments come after the name of the Onda JAR file in the command line that invokes the java launcher.)

4.4  Running Onda

The Onda application is an executable JAR (Java archive) file that requires a Java runtime environment. The JAR file can be run directly or indirectly in the ways described above.

If you run the Onda application from a command line, the command line may contain configuration properties, including the location of a configuration file. The following subsections describe how to run Onda from a command line.

4.4.1  Running under Linux/UNIX

Assuming that your PATH environment variable includes the path to the java tool and that you have copied onda.jar to the directory /home/slothrop/bin/onda/, the command

will run the Onda application with a GUI, and the command

will run Onda as a console application with a command to compress the file shriek.wav.

The file onda.png can be used as the icon for the Onda application.

4.4.2  Running under Windows

Onda can be run as a console application or as a GUI application. You can use the java launcher to run the application in both modes with a console window. If you want to run Onda as a GUI application without a console window, you can use the javaw launcher. Assuming that your PATH environment variable includes the path to the java and javaw tools and that you have copied onda.jar to the directory C:\Program Files\Onda\, the command

will run the Onda application with a GUI, and the command

will run Onda as a console application with a command to compress the file shriek.wav.

The file onda.ico can be used as the icon for the Onda application.

4.5  Uninstalling Onda

Onda does not have an automated means of uninstallation. To remove it from your system, delete the file onda.jar from the location to which it was written when you installed Onda. If you want to remove Onda completely, you should also delete the configuration file, onda-config.xml, which may be at its default location, and any other files that were installed (eg, the manual).

5  Configuration

[ Table of contents ]

When it starts up, Onda is configured with configuration properties that are read from two sources: the command line that is used to run the Java launcher and a configuration file whose location may be explicitly specified. If the same property is specified on the command line and in a configuration file, the value from the configuration file takes precedence.

The recommended method of setting the properties in a configuration file is with the Preferences command. For command-line properties, which must be edited manually, the form of the property values is given in an appendix, and it can also be inferred by generating a configuration file with the desired values and inspecting the contents of the file.

5.1  Command-line properties

When Onda is run by means of the java launcher, configuration properties may be specified on the command line using the standard Java form -Dname="value"; eg, -Dapp.compression.blockLength="512". (The quotation marks around the value aren't necessary if the value doesn't contain spaces.) Onda's command-line configuration properties all have the prefix app. . A list of all the properties that are recognised by Onda is given in an appendix.

One particular property, app.configDir, is used to specify the directory that contains a configuration file, as described below. The value of the app.configDir property may contain special constructs for system properties, environment variables and the user's home directory.

5.2  Configuration file

The configuration file is named onda-config.xml. Onda doesn't require a configuration file: it uses a default value for any configuration property that is missing from the source(s) of configuration. Similarly, if it finds a property value to be invalid, Onda will display a message to this effect and use the default value of the property. If the configuration file contains a property that was specified on the command line, the value from the configuration file is used.

If the configuration has changed when you exit the application normally (ie, using the Exit command or an equivalent), Onda will save its configuration to a configuration file. If a configuration file was read on startup, it will overwrite that file; otherwise, it will write a configuration file to the default directory described above, unless the value of the app.configDir property was an empty string.

A configuration file can be written explicitly with the Save configuration command within the Preferences dialog.

5.2.1  Location of the configuration file

When it starts up, Onda is informed of the location of the configuration file with the app.configDir property, which may be set in two ways:

• in a file named onda-properties.xml that resides in the same directory as the onda.jar file, or
• on the command line that runs the java launcher.

If the app.configDir property is set both in the properties file and on the command line, the value in the properties file takes precedence.

The onda-properties.xml file is normally written by the installer. If you create the file manually, it should have the following form, with the example pathname replaced by the actual pathname:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="app.configDir">/home/slothrop/.blankaspect/onda</entry>
</properties>

If the configuration file were located in a directory named config in the user's home directory, the sample command lines given above would become:

The existence and value of the app.configDir property determines the locations that are searched for a configuration file:

• If the app.configDir property exists and the property value is an empty string, Onda will start without a configuration file. No configuration file will be written when the application exits.
• If the app.configDir property exists and the property value is not empty, Onda will look for a configuration file in the directory specified by the property. An error message is displayed if a configuration file is not found in the specified directory.
• If the app.configDir property does not exist, Onda will look for a configuration file at two other locations:
  1. The current working directory
     The current working directory, which is denoted by the environment variable $PWD on Linux/UNIX systems, depends on the system and the way in which Onda was run.
  2. The default directory
     On Linux/UNIX systems, the default directory is $HOME/.blankaspect/onda, where $HOME is the environment variable that denotes the user's home directory. On Windows systems, the default directory is %APPDATA%\blankaspect\onda, where %APPDATA% is a system environment variable.

6  Command-line arguments in console mode

[ Table of contents ]

Onda runs in console mode if command-line arguments are passed to it when it starts up. Valid arguments are of three types: options, commands and input pathnames. Options and commands must have '--' prefixed to them; there are no single-character short forms that have a prefix of a single hyphen. The name and value of an option may be separated with whitespace or with a '=' character.

In keeping with convention, the command-line syntax for the Onda application (shown below and in response to Onda's --help command) implies that the application is invoked with the command onda. However, this is only a convention; the actual form of a command line that invokes Onda is described in the relevant sections for Linux/UNIX and Windows.

The three main commands — Compress, Expand and Validate — are described in the section on commands.

7  The display in GUI mode

[ Table of contents ]

The main window of the Onda application in GUI mode is equivalent to a dialog box. The size of the window cannot be changed directly, though it can be changed indirectly (for example, by changing the fonts in the user preferences).

The Input file or directory combo box, the Input mode drop-down list and the Recursive checkbox are used together to specify the input files or directories of a Compress, Expand or Validate command. You can specify a pathname in the Input file or directory combo box by any of the following methods:

• type text directly into the field of the combo box;
• use drag-and-drop: drag a pathname from a suitable source (eg, a file manager) and drop it onto the combo box;
• copy a pathname from a suitable source (eg, a file manager) and paste it into the field of the combo box;
• select a pathname from the drop-down list of the combo box;
• use the browse button ("…") adjacent to the field to bring up a file-selection dialog whose selection will be displayed in the field.

Input mode = Direct

If the pathname in the Input file or directory field denotes a file, it will be the input file of a subsequent Compress, Expand or Validate command. If the pathname denotes a directory, the files in the directory will be processed if they have a filename suffix appropriate to the command: for the Compress command, files with the filename suffixes .aif, .aiff, .wav or .wave are processed; for the Expand and Validate commands, files with the filename suffix .onda are processed. If the Recursive checkbox is selected, all appropriate files in directories below the specified directory are processed too.

Input mode = List

The pathname in the Input file or directory field is assumed to denote a text file that contains a list of input pathnames and, optionally, output directories. Each non-empty line of the file is deemed to contain a single input pathname, which may be followed by one or more tab characters (U+0009) and the pathname of an output directory. Each input pathname in the list is treated as though it was entered as a direct input in the Input file or directory field, and any associated output directory is treated as though it was entered in the Output directory field.

If the Input file or directory field is empty, the Compress, Expand and Validate commands will each display a file-selection dialog to allow you to choose the input file.

The Output directory combo box specifies the directory to which the output files of the Compress and Expand commands will be written. If the field is empty, each output file will be written to the same directory as its input file. (The Output directory field is ignored by the Validate command.) You can specify a pathname in the Output directory combo box by the methods described above for the Input file or directory combo box.

The arrow buttons alongside the Input file or directory combo box and the Output directory combo box allow you to copy a pathname from one combo box to another.

During compression, expansion or validation, the progress of the operation is shown in a separate dialog box. A configuration property, appearance.showOverallProgress, determines whether the dialog box shows the overall progress of the operation when processing multiple files.

The six buttons at the bottom of the main window are associated with the main commands.

7.1  Drag-and-drop

If your system supports the dragging and dropping of files (for example, from a file manager such as GNOME Nautilus or Windows Explorer), there are three areas of the main window of Onda that you can drag and drop files or directories onto: the Input file or directory combo box, the Output directory combo box, and the remaining area of the window, referred to as the main panel.

The Input file or directory combo box and the Output directory combo box will both accept the dragging and dropping of a single file or directory, whose pathname will be displayed in the field of the combo box. When you drag a file or directory onto one of the combo boxes, take care that you don't drop it onto the main panel.

The main panel will accept the dragging and dropping of multiple files, which will initiate a sequence of compression and expansion operations on the files that were dropped, according to the suffix of each filename: files with the .onda suffix will be expanded; other files will be compressed if they have one of the supported audio file formats. Any directory that is dropped onto the main panel will be ignored. Before the compression and expansion operations begin, you will be asked to confirm that you want to proceed.

8  Commands

[ Table of contents ]

This section describes the commands that are available in GUI mode, which are issued from the buttons in the main window. The first three commands — Compress, Expand and Validate — are also available in console mode.

8.1  Compress

The Compress command compresses each valid input file using the Onda algorithm with the block length denoted by the compression.blockLength configuration property or a default block length of 256. The name of the output file is the name of the input file with an additional .onda suffix. If an output directory is specified, all output files are written to that directory; otherwise, each output file is written to the same directory as its input file. If the input pathname is a directory and the recursive option is selected, the directory structure below the input directory is reproduced in the output directory.

The type (AIFF or WAVE) of an input file is inferred from the suffix of its filename: a file with the suffix .aif or .aiff is assumed to be an AIFF file, and a file with the suffix .wav or .wave is assumed to be a WAVE file. If the filename suffix is not recognised, the first few bytes of the file are read to determine its type. An error occurs if the file type that is implied by the filename suffix does not correspond to the actual file type.

A WAVE file may contain either PCM (raw) sample data or sample data that have already been compressed with a lossless or lossy compression algorithm such as one of the MPEG audio algorithms. An AIFF file (as distinct from an AIFF-C file) can contain only raw sample data. Onda can compress only files that contain raw sample data.

In GUI mode, the result of a compression operation (including the compression ratio and the time taken) is written to an internal log, which can be displayed with the View log command. In console mode, the information is written to the console.

8.1.1  Preserving chunks in AIFF and WAVE files

An AIFF file is an instance of an IFF file, and a WAVE file is an instance of an RIFF file. Both types of file consist of a number of chunks; each chunk has a 4-byte ASCII identifier (ID). An AIFF file must have at least a Common chunk (ID = "COMM") and a sound data chunk (ID = "SSND"), whereas a WAVE file, if it contains raw sample data, must have at least a Format chunk (ID = "fmt ") and a sound data chunk (ID = "data"). Both types of file may have other, ancillary chunks, some of which extend the file format in ways that are essential to a particular application. For example, files of the Broadcast Wave Format (BWF) — an extension to the WAVE format — include a chunk with the ID "bext", which contains, among other things, information that is used to synchronise the BWF file with other audio or video sources. Such chunks need to be preserved in order to maintain the usefulness of the original audio file.

You can specify, by means of a filter, the ancillary chunks that will be preserved when an AIFF or WAVE file is compressed. (The critical Common/Format and data chunks are always preserved.) A filter is specific to one file type, AIFF or WAVE. It comprises a set of chunk IDs, and is either inclusive or exclusive. When a file is compressed, a chunk is preserved if its ID is contained in an inclusive filter or not contained in an exclusive filter. In console mode, a filter can be specified as a command-line option; if no filter is specified, all ancillary chunks are preserved. In GUI mode, the filter is selected from a list of filters in a configuration file, and the filter properties can be edited from within the Preferences dialog.

The preserved chunks are merged, then compressed with Java's built-in zlib compression library, which uses the DEFLATE algorithm. When an Onda file is expanded, the chunks are restored in the order in which they appeared in the original file. A list of preserved chunks is written to the log in GUI mode, or to the console in console mode.

Onda files that contain preserved chunks have a different version number from those that don't contain preserved chunks, which prevents them from being expanded or validated by version 1.0 of the Onda application.

8.2  Expand

The Expand command decompresses files that have been compressed with the Onda application. If the input filename has the suffix .onda, the name of the output file is the name of the input file with its .onda suffix removed; otherwise, the name of the output file is the name of the input file with a numerical suffix appended to its base filename. If an output directory is specified, all output files are written to that directory; otherwise, each output file is written to the same directory as its input file. If the input pathname is a directory and the recursive option is selected, the directory structure below the input directory is reproduced in the output directory.

The type (AIFF or WAVE) of an output file is inferred from the suffix of the name of the input file after the .onda suffix has been removed: a file with the suffix .aif or .aiff is assumed to be an AIFF file, and a file with the suffix .wav or .wave is assumed to be a WAVE file. If the filename suffix is not recognised, the file type is determined from the ancillary chunks of the original file that were preserved in the Onda file. If the file type cannot be determined by either of these methods, you will be asked to select it. An error occurs if the file type that is implied by the filename suffix does not correspond to the file type of any preserved chunks.

In GUI mode, the result of an expansion operation is written to an internal log, which can be displayed with the View log command. In console mode, the information is written to the console.

8.3  Validate

The Validate command tests the validity of files that have been compressed with the Onda application. It is intended to allow the integrity of archives to be checked without the need to decompress each file. It validates the sample data, along with the data from any ancillary chunks in the original file that were preserved during compression.

In GUI mode, the result of a validation operation is written to an internal log, which can be displayed with the View log command. In console mode, the information is written to the console.

8.4  View log

In GUI mode, Onda maintains an internal log of the result of Compress, Expand and Validate commands; the View log command displays this log in a dialog box. Within the log dialog, the Clear command (Alt+X) deletes the entire contents of the log, and the Copy command (Alt+C) copies the contents of the log to the system clipboard so that it can be pasted into another application. A portion of the log can be copied to the clipboard from the text area of the log dialog by selecting the text with the mouse cursor and pressing Ctrl+C.

In the log, error messages have '!' prefixed to them.

8.5  Preferences

The Preferences command brings up a tabbed dialog box in which the configuration properties of Onda can be edited. The properties on the various tabbed pages are described below.

Some of the configuration properties in the Preferences dialog are edited with a spinner — a graphical component that consists of a text field adjacent to a pair of small buttons. The value in the text field may be edited manually, or it may be incremented and decremented by one of the following methods:

• clicking on the small up/down buttons;
• pressing the up/down arrow keys;
• rotating the mouse wheel with the mouse cursor over the spinner when the text field has keyboard focus (ie, the caret is displayed in the field).

Using the last two methods, the amount by which the value is incremented or decremented can be modified by holding down the Ctrl, Shift or Ctrl+Shift keys, which correspond to increments of 10, 100 and 1000 respectively.

Some of the configuration properties will take effect when the Preferences dialog is accepted (by closing it with OK); other properties (eg, the look-and-feel and fonts) will not take effect until the next time that Onda is run.

The configuration file is normally saved automatically when Onda exits, if the configuration has changed. The Save configuration command in the Preferences dialog can be used to save a configuration file explicitly.

8.6  Exit

This command terminates the application.

Appendix A:  Special constructs in pathnames

[ Table of contents ]

Where indicated elsewhere in this document, pathname properties in Onda can contain special constructs for system properties, environment variables and the user's home directory. The special constructs are expanded when the pathname is used.

System properties and environment variables

Java system properties (eg, the user's home directory, user.home) and environment variables (eg, PATH) are referenced by enclosing them between '${' and '}'; that is, they must have the form ${<name>}. A Java system property takes precedence over an environment variable with the same name.

• Example: ${user.home}/projects

• Example: ${HOME}/projects

A Java system property can be specified by prefixing sys. to it.

• Example: ${sys.user.home}/projects

An environment variable can be specified by prefixing env. to it.

• Example: ${env.HOME}/projects

User's home directory

A leading '~' in a pathname is expanded into the user's home directory using the user.home system property, which is usually equivalent to the environment variable $HOME on Linux/UNIX systems or %USERPROFILE% on Windows systems.

• Example: ~/projects

Appendix B:  Configuration properties

[ Table of contents ]

The table below lists the configuration properties of Onda. Apart from the app.configDir property, which, for obvious reasons, cannot be used within a configuration file, and the chunkFilter properties, which are ignored if they are given as command-line properties, all properties can be used in the two configuration locations: command-line properties and configuration file.

When used in a -D command-line property, app. must be prefixed to the property key (eg, app.general.mainWindowLocation).

The <index> of an indexed property key (eg, chunkFilter.aiff.filter) is a three-digit decimal-string representation of the zero-based index of the property (eg, the third AIFF chunk filter is chunkFilter.aiff.filter.002).

Any commas (',') or backslash characters ('\') in the name of a font must be escaped by prefixing a '\' character to them.

In the table below, the initial character of an italicised component of a property value denotes its data type according to the following convention:

Appendix C:  Providing feedback about Onda

[ Table of contents ]

The Onda project is hosted by SourceForge. You can submit bug reports, feature requests and suggestions for improvement through the SourceForge website, but the mechanism for doing so may change depending on the facilities that SourceForge provides. For current information, please see the feedback page for Blank Aspect projects.

When reporting a problem with Onda, please try to include enough relevant information to enable the problem to be reproduced. You should include at least the following information:

• the version number of Onda,
• the name and version number of the operating system,
• the name and version number of the Java runtime environment,
• a description of the problem.

A Java stack trace, if one is available, would be helpful.

Appendix D:  Onda compression algorithm and Onda file formats

[ Table of contents ]

There is a link to a document containing details of the Onda compression algorithm and the formats, old and new, of the compressed files produced by the Onda application on the Onda website.