AudioConverter

/**
 * Copyright (c) 2011, The University of Southampton and the individual contributors.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 *   * 	Redistributions of source code must retain the above copyright notice,
 * 	this list of conditions and the following disclaimer.
 *
 *   *	Redistributions in binary form must reproduce the above copyright notice,
 * 	this list of conditions and the following disclaimer in the documentation
 * 	and/or other materials provided with the distribution.
 *
 *   *	Neither the name of the University of Southampton nor the names of its
 * 	contributors may be used to endorse or promote products derived from this
 * 	software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/**
 *
 */
package org.openimaj.audio.conversion;

import org.openimaj.audio.AudioFormat;
import org.openimaj.audio.AudioStream;
import org.openimaj.audio.SampleChunk;
import org.openimaj.audio.processor.AudioProcessor;

/**
 *	A class that will work out which processors to instantiate to provide
 *	with a complete conversion from one audio format to another.
 *
 *	@author David Dupplaw (dpd@ecs.soton.ac.uk)
 *  @created 13 May 2013
 */
public class AudioConverter extends AudioProcessor
{
	/** The input format */
	private AudioFormat inputFormat = null;

	/** The calculated audio processor */
	private AudioProcessor processor = null;

	/**
	 * 	Chainable constructor that takes the stream to chain and the
	 * 	output format to convert the stream to.
	 *	@param stream The stream to chain to
	 *	@param output The required output format
	 */
	public AudioConverter( final AudioStream stream, final AudioFormat output )
	{
		super( stream );
		this.inputFormat = stream.getFormat().clone();
		this.setFormat( output.clone() );
		this.processor = AudioConverter.calculateProcess( this.inputFormat, output );
	}

	/**
	 * 	Constructor that takes the input and output formats.
	 *	@param input The input format
	 *	@param output The output format
	 */
	public AudioConverter( final AudioFormat input, final AudioFormat output )
	{
		this.inputFormat = input.clone();
		this.setFormat( output.clone() );
		this.processor = AudioConverter.calculateProcess( input, output );
	}

	/**
	 * 	Calculates the chain of processors that will convert from one format to the
	 * 	other and will return the first in the chain. If there is no processing to be
	 * 	done the method will return null.
	 *
	 *	@param input The input format
	 *	@param output The output format.
	 *	@return The first processor in the stream.
	 */
	public static AudioProcessor calculateProcess( final AudioFormat input, final AudioFormat output )
	{
		// If the input and output formats are the same, then there's
		// no processing to do, so we return null.
		if( input.equals( output ) )
			return null;

		AudioProcessor ap = null;

		// Note that we construct this chain back-to-front. So, if
		// all the processors will be used, then the channel processor,
		// then sample rate, then bit depth processor.  This should be
		// the most efficient order.

		// Check if the endian is the same.
		if( input.isBigEndian() != output.isBigEndian() )
			throw new IllegalArgumentException( "Cannot convert "+input+" to "+output+
					". There is no endian conversion implemented yet." );

		// Check if the signedness is the same
		if( input.isSigned() != output.isSigned() )
			throw new IllegalArgumentException( "Cannot convert "+input+" to "+output+
					". There is no sign conversion implemented yet." );

		// Check if the sample rates are different
		if( input.getSampleRateKHz() != output.getSampleRateKHz() )
			ap = AudioConverter.getProcessor( ap, new SampleRateConverter(
					SampleRateConverter.SampleRateConversionAlgorithm.LINEAR_INTERPOLATION,
						AudioConverter.getFormatSR( ap, output ) ) );

		// Check if the bits are different
		if( input.getNBits() != output.getNBits() )
			ap = AudioConverter.getProcessor( ap, new BitDepthConverter(
					BitDepthConverter.BitDepthConversionAlgorithm.NEAREST,
						AudioConverter.getFormatBits( ap, output ) ) );

		// Check if the channels are different
		if( input.getNumChannels() != output.getNumChannels() )
		{
			if( output.getNumChannels() == 1 )
					ap = AudioConverter.getProcessor( ap, new MultichannelToMonoProcessor() );
			else	throw new IllegalArgumentException( "Cannot convert "+input+" to "+output+
								". Unable to find an appropriate channel converter." );
		}

		return ap;
	}

	/**
	 * 	Updates the number of bits in the source processor's format to match the output format.
	 *
	 *	@param ap The source processor
	 *	@param output The output format
	 *	@return The fixed source format
	 */
	private static AudioFormat getFormatBits( final AudioProcessor ap , final AudioFormat output )
	{
		if( ap == null ) return output;
		final AudioFormat f = ap.getFormat().clone();
		f.setNBits( output.getNBits() );
		return f;
	}

	/**
	 * 	Updates the sample rate in the source processor's format to match the output format.
	 *
	 *	@param ap The source processor
	 *	@param output The output format
	 *	@return The fixed source format
	 */
	private static AudioFormat getFormatSR( final AudioProcessor ap, final AudioFormat output )
	{
		if( ap == null ) return output;
		final AudioFormat f = ap.getFormat().clone();
		f.setSampleRateKHz( output.getSampleRateKHz() );
		return f;
	}

	/**
	 *	Gets the top in the chain of processors (when constructing the chain in reverse order).
	 *	That is, the second processor will always be returned from this method. If the first
	 *	processor is not null, it will be made the source stream for the second processor.
	 *
	 *	@param ap The source processor
	 *	@param ap2 The destination processor
	 *	@return The destination processor
	 */
	private static AudioProcessor getProcessor( final AudioProcessor ap, final AudioProcessor ap2 )
	{
		if( ap == null )
			return ap2;
		ap2.setUnderlyingStream( ap );
		return ap2;
	}

	@Override
	public SampleChunk process( final SampleChunk sample ) throws Exception
	{
		return this.processor.process( sample );
	}

	/**
	 * 	Same as {@link #getFormat()} for this class - returns the output format.
	 *	@return The output format.
	 */
	public AudioFormat getOutputFormat()
	{
		return this.getFormat();
	}
}