Amplituda

To use Amplituda, initialize the library with a Context, then call processAudio with the path to your audio file. The processing is asynchronous and returns a result object containing the amplitude data and audio metadata.

Implementation Steps

1. Initialize: Create an instance of Amplituda using your application or activity context.
2. Process: Call processAudio(path) and provide callbacks for success and failure.
3. Extract Data: Use the AmplitudaResult object to retrieve amplitude lists, duration, and audio type.

Available Result Data

• amplitudesAsList(): Returns a List<Integer> of all processed amplitude samples.
• amplitudesForSecond(int second): Returns a List<Integer> of amplitudes for a specific second.
• getAudioDuration(AmplitudaResult.DurationUnit unit): Returns the audio duration in the specified unit (e.g., SECONDS).
• getAudioSource(): Returns the source path of the audio.
• getInputAudioType(): Returns the InputAudio.Type of the processed file.

Error Handling

If processing fails, the exception can be checked against AmplitudaIOException to handle file-related errors.

/* Step 1: create Amplituda */
Amplituda amplituda = new Amplituda(context);

/* Step 2: process audio and handle result */
amplituda.processAudio("/storage/emulated/0/Music/Linc - Amplituda.mp3")
        .get(result -> {
            List<Integer> amplitudesData = result.amplitudesAsList();
            List<Integer> amplitudesForFirstSecond = result.amplitudesForSecond(1);
            long duration = result.getAudioDuration(AmplitudaResult.DurationUnit.SECONDS);
            String source = result.getAudioSource();
            InputAudio.Type sourceType = result.getInputAudioType();
            // etc
        }, exception -> {
            if(exception instanceof AmplitudaIOException) {
                System.out.println("IO Exception!");
            }
        });

To reduce the size of the output data, you can pass Compress parameters to processAudio. This allows you to specify a preferred number of samples per second and a compression type.

Compression Types:

• Compress.SKIP: Takes the first preferredSamplesPerSecond and skips the rest.
• Compress.PEEK: Takes a peek of the preferredSamplesPerSecond and skips the rest.
• Compress.AVERAGE: Merges all samples to match the preferredSamplesPerSecond count.

Example: For a 10-second audio, Compress.withParams(Compress.AVERAGE, 5) will result in approximately 50 samples (5 samples per second * 10 seconds).

// Example: input audio duration - 10 seconds

amplituda.processAudio(<audio>, Compress.withParams(Compress.AVERAGE, 1));
// Output: data with 1 sample per 1 second.

amplituda.processAudio(<audio>, Compress.withParams(Compress.AVERAGE, 5));
// Output: data with 5 sample per 1 second

To retrieve the processed data from AmplitudaProcessingOutput<T>, use the .get() method. This method has several overloads to support both callback-based and synchronous styles, as well as error handling.

Error Handling: Exceptions can be caught and checked using instanceof. Common exceptions include:

• AmplitudaIOException
• AmplitudaProcessingException

AmplitudaProcessingOutput<T> processingOutput;
// . . . process audio . . .

// Overload #1: result as a callback with error listener
processingOutput.get(result -> { 
        /* handle result here */ 
    }, exception -> { 
        /* handle errors here */ 
    });

// Overload #2: result as a callback without error listener
processingOutput.get((AmplitudaSuccessListener<T>) result -> {
        /* handle result here */
    });

// Overload #3: result as a returned object with error listener
result = processingOutput.get((AmplitudaException exception) -> {
        /* handle errors here */
    });

// Overload #4: result as a returned object without error listener
result = processingOutput.get();

// Example of specific error handling
processingOutput.get((AmplitudaException exception) -> {
    if(exception instanceof AmplitudaIOException) {
        // Handle io exceptions
    } else if(exception instanceof AmplitudaProcessingException) {
        // Handle processing exceptions
    } else {
        exception.printStackTrace();
    }
});

Amplituda provides a built-in caching mechanism to reuse processed audio data. You can configure this using Cache.withParams().

Cache States:

• Cache.REUSE: Uses cached data if available; otherwise, processes the audio and writes it to the cache.
• Cache.REFRESH: Updates existing cache data (use this only when you need to force a refresh).

You can optionally provide a unique String key for each audio to manage the cache manually.

Cache Management:

• amplituda.clearCache(): Clears all cache data.
• amplituda.clearCache(<audio>): Clears cache for a specific audio.
• amplituda.clearCache("key", true): Clears cache by a custom key.

// Enable amplituda cache feature:
amplituda.processAudio(<audio>, Cache.withParams(Cache.REUSE));

// Cache with custom key. The key should be unique for each audio
amplituda.processAudio(<audio>, Cache.withParams(Cache.REUSE, "my-unique-key"));

// Clear all cache data
amplituda.clearCache();

// Clear cache data for specific audio (if exist)
amplituda.clearCache("/storage/emulated/0/Music/Linc - Amplituda.mp3", false);

// Clear cache data by custom key.
amplituda.clearCache("my-unique-key", true);

Once you have an AmplitudaResult<T>, you can extract the data in various formats:

• amplitudesAsList(): Returns a List<Integer> of all samples.
• amplitudesForSecond(int second): Returns a List<Integer> for a specific second of audio.
• amplitudesAsJson(): Returns a JSON formatted String.
• amplitudesAsSequence(SequenceFormat format): Returns a formatted String sequence.

Sequence Formats:

• AmplitudaResult.SequenceFormat.SINGLE_LINE: A single line of numbers.
• AmplitudaResult.SequenceFormat.SINGLE_LINE (with delimiter): A single line with a custom delimiter (e.g., " * ").
• AmplitudaResult.SequenceFormat.NEW_LINE: Each sample on a new line.

AmplitudaResult<T> result;
 
// Get result as list:
List<Integer> samples = result.amplitudesAsList(); 
 
// Get result as list only for second `1`
List<Integer> samplesForFirstSecond = result.amplitudesForSecond(1);
 
// Get result as json format String
System.out.println(result.amplitudesAsJson());

// Get result as single line sequence format String (horizontal String)
System.out.println(result.amplitudesAsSequence(
        AmplitudaResult.SequenceFormat.SINGLE_LINE)
);

// Get result as single line sequence format String with custom delimiter `*` (horizontal String)
System.out.println(result.amplitudesAsSequence(
        AmplitudaResult.SequenceFormat.SINGLE_LINE, " * ")
);

// Get result as new line sequence format String  
System.out.println(result.amplitudesAsSequence(
        AmplitudaResult.SequenceFormat.NEW_LINE)
);

Implement AmplitudaProgressListener to track the status of the audio processing task. The onProgress method provides a ProgressOperation and an integer representing the percentage (0-100).

Progress Operations:

• PROCESSING: General audio processing.
• DECODING: Decoding raw or resource audio.
• DOWNLOADING: Downloading audio from a URL.

amplituda.processAudio(
    <audio>,
    new AmplitudaProgressListener() {
        @Override
        public void onStartProgress() {
            super.onStartProgress();
            System.out.println("Start Progress");
        }

        @Override
        public void onStopProgress() {
            super.onStopProgress();
            System.out.println("Stop Progress");
        }

        @Override
        public void onProgress(ProgressOperation operation, int progress) {
            String currentOperation = "";
            switch (operation) {
                case PROCESSING: currentOperation = "Process audio"; break;
                case DECODING: currentOperation = "Decode resource"; break;
                case DOWNLOADING: currentOperation = "Download audio from url"; break;
            }
            System.out.printf("%s: %d%% %n", currentOperation, progress);
        }
    }
)