Package net.paulhertz.pixelaudio.schedule

# Class AudioUtility

java.lang.Object
net.paulhertz.pixelaudio.schedule.AudioUtility

public final class AudioUtility extends Object
Utility conversions for audio.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `(package private) static enum`
  `AudioUtility.NormalizationMode`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `private static final double`
  `LOG2`
  Precomputed log(2) for efficiency.
  `static final double`
  `SEMITONE_FAC`
  Constant: 2^(1/12), the ratio of one semitone.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `private`
  `AudioUtility()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static float`
  `computePeak(float[] signal)`
  Computes the peak absolute sample value of a signal.
  `static float`
  `computeRMS(float[] signal)`
  Computes the RMS (root mean square) level of a signal.
  `static float`
  `dbToLinear(float dB)`
  Converts a gain value in decibels (dB) to a linear amplitude multiplier.
  `static int`
  `fileSamplesRequiredForDisplay(int mapSize, float fileSampleRate, float audioOutRate)`
  `static float`
  `frequencyPianoKey(float freq)`
  Convert frequency to fractional MIDI-style key number.
  `static float`
  `linearToDb(float linear)`
  `static long`
  `millisToSamples(double millis, double sampleRate)`
  `static void`
  `normalizePeakDb(float[] signal, float targetPeakDB)`
  `static void`
  `normalizePeakLevel(float[] signal, float targetPeakLevel)`
  `static float`
  `normalizeRMS(float[] signal, float targetDB)`
  Normalizes a single-channel signal array to a target RMS level in dBFS.
  `static void`
  `normalizeRmsWithCeiling(float[] signal, float targetRmsDB, float peakCeilingDB)`
  `static float`
  `pianoKeyFrequency(float keyNumber)`
  Convert MIDI-style key number to frequency (A4 = 440 Hz, key 49).
  `static float`
  `ratioToSemitones(float ratio)`
  Convert frequency ratio to semitone offset.
  `static ddf.minim.MultiChannelBuffer`
  `resampleMCB(ddf.minim.MultiChannelBuffer src, float sourceRate, float targetRate)`
  Resamples all channels in a MultiChannelBuffer from sourceRate to targetRate.
  `static ddf.minim.MultiChannelBuffer`
  `resampleMCBToOutput(ddf.minim.MultiChannelBuffer src, float sourceRate, ddf.minim.AudioOutput out)`
  Convenience: resample MultiChannelBuffer from sourceRate to match AudioOutput.
  `static float[]`
  `resampleMono(float[] source, float sourceRate, float targetRate)`
  Resamples a mono buffer from sourceRate to targetRate using linear interpolation.
  `static float[]`
  `resampleMonoToOutput(float[] source, float sourceRate, ddf.minim.AudioOutput out)`
  Convenience: resample mono buffer from sourceRate to match AudioOutput sample rate.
  `static double`
  `samplesToMillis(long samples, double sampleRate)`
  `static void`
  `saveAudioTo32BitPCMFile(float[] samples, float sampleRate, String fileName)`
  Saves audio data to a 32-bit floating point format that has higher resolution than 16-bit integer PCM.
  `static void`
  `saveAudioToFile(float[] samples, float sampleRate, String fileName)`
  Saves audio data to 16-bit integer PCM format, which Processing can also open.
  `static void`
  `saveStereoAudioTo32BitPCMFile(float[] leftChannel, float[] rightChannel, float sampleRate, String fileName)`
  Saves stereo audio data to a 32-bit floating point format that has higher resolution than 16-bit integer PCM.
  `static void`
  `saveStereoAudioToFile(float[] leftChannel, float[] rightChannel, float sampleRate, String fileName)`
  Saves stereo audio data to 16-bit integer PCM format, which Processing can also open.
  `static long`
  `secsToSamples(double secs, double sampleRate)`
  `static float`
  `semitonesToRatio(float semitones)`
  Convert semitone offset to frequency ratio.
  `static float`
  `transposeFrequency(float freq, float semitones)`
  Apply a semitone offset directly to a frequency.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### SEMITONE_FAC

    public static final double SEMITONE_FAC
    Constant: 2^(1/12), the ratio of one semitone.

  - ### LOG2

    private static final double LOG2
    Precomputed log(2) for efficiency.

- ## Constructor Details

  - ### AudioUtility

    private AudioUtility()

- ## Method Details

  - ### millisToSamples

    public static long millisToSamples(double millis, double sampleRate)

  - ### samplesToMillis

    public static double samplesToMillis(long samples, double sampleRate)

  - ### secsToSamples

    public static long secsToSamples(double secs, double sampleRate)

  - ### dbToLinear

    public static float dbToLinear(float dB)
    Converts a gain value in decibels (dB) to a linear amplitude multiplier. 0.0 dB -> 1.0 -6.0 dB -> ~0.501 +6.0 dB -> ~1.995
    Parameters:
      `dB` - gain in decibels
    Returns:
      linear gain multiplier

  - ### linearToDb

    public static float linearToDb(float linear)
    Parameters:
      `linear` - decimal gain value, for example from a UI slider
    Returns:
      values in decibels for linear

  - ### semitonesToRatio

    public static float semitonesToRatio(float semitones)
    Convert semitone offset to frequency ratio.
    Parameters:
      `semitones` - number of semitones (can be fractional)
    Returns:
      frequency ratio (>0) Examples: 12 -> 2.0 0 -> 1.0 -12 -> 0.5

  - ### ratioToSemitones

    public static float ratioToSemitones(float ratio)
    Convert frequency ratio to semitone offset.
    Parameters:
      `ratio` - frequency ratio (>0)
    Returns:
      semitone offset (can be fractional)

  - ### pianoKeyFrequency

    public static float pianoKeyFrequency(float keyNumber)
    Convert MIDI-style key number to frequency (A4 = 440 Hz, key 49).

  - ### frequencyPianoKey

    public static float frequencyPianoKey(float freq)
    Convert frequency to fractional MIDI-style key number.

  - ### transposeFrequency

    public static float transposeFrequency(float freq, float semitones)
    Apply a semitone offset directly to a frequency.

  - ### computePeak

    public static float computePeak(float[] signal)
    Computes the peak absolute sample value of a signal.
    Parameters:
      `signal` - The audio samples
    Returns:
      Maximum absolute sample value (linear scale)

  - ### computeRMS

    public static float computeRMS(float[] signal)
    Computes the RMS (root mean square) level of a signal.
    Parameters:
      `signal` - The audio samples
    Returns:
      RMS value (linear scale)

  - ### normalizeRMS

    public static float normalizeRMS(float[] signal, float targetDB)
    Normalizes a single-channel signal array to a target RMS level in dBFS.
    Parameters:
      `signal` - The audio samples to normalize (modified in place)
      `targetDB` - The peak level in dB (e.g. -3.0f for moderately loud, -12.0f for safe headroom)
    Returns:
      gain applied to signal

  - ### normalizePeakDb

    public static void normalizePeakDb(float[] signal, float targetPeakDB)

  - ### normalizePeakLevel

    public static void normalizePeakLevel(float[] signal, float targetPeakLevel)

  - ### normalizeRmsWithCeiling

    public static void normalizeRmsWithCeiling(float[] signal, float targetRmsDB, float peakCeilingDB)

  - ### fileSamplesRequiredForDisplay

    public static int fileSamplesRequiredForDisplay(int mapSize, float fileSampleRate, float audioOutRate)

  - ### resampleMono

    public static float[] resampleMono(float[] source, float sourceRate, float targetRate)
    Resamples a mono buffer from sourceRate to targetRate using linear interpolation.
    Parameters:
      `source` - mono samples at sourceRate
      `sourceRate` - sample rate of the source buffer (Hz)
      `targetRate` - desired sample rate (Hz)
    Returns:
      new float[] at targetRate

  - ### resampleMonoToOutput

    public static float[] resampleMonoToOutput(float[] source, float sourceRate, ddf.minim.AudioOutput out)
    Convenience: resample mono buffer from sourceRate to match AudioOutput sample rate.

  - ### resampleMCB

    public static ddf.minim.MultiChannelBuffer resampleMCB(ddf.minim.MultiChannelBuffer src, float sourceRate, float targetRate)
    Resamples all channels in a MultiChannelBuffer from sourceRate to targetRate. Produces a new MultiChannelBuffer at targetRate. For PixelAudio you may only need channel 0 (mono); this is available mainly for completeness.

  - ### resampleMCBToOutput

    public static ddf.minim.MultiChannelBuffer resampleMCBToOutput(ddf.minim.MultiChannelBuffer src, float sourceRate, ddf.minim.AudioOutput out)
    Convenience: resample MultiChannelBuffer from sourceRate to match AudioOutput.

  - ### saveAudioToFile

    public static void saveAudioToFile(float[] samples, float sampleRate, String fileName) throws IOException, UnsupportedAudioFileException
    Saves audio data to 16-bit integer PCM format, which Processing can also open.
    Parameters:
      `samples` - an array of floats in the audio range (-1.0f, 1.0f)
      `sampleRate` - audio sample rate for the file
      `fileName` - name of the file to save to
    Throws:
      `IOException` - an Exception you'll need to handle to call this method (see keyPressed entry for 's')
      `UnsupportedAudioFileException` - another Exception (see keyPressed entry for 's')

  - ### saveAudioTo32BitPCMFile

    public static void saveAudioTo32BitPCMFile(float[] samples, float sampleRate, String fileName) throws IOException
    Saves audio data to a 32-bit floating point format that has higher resolution than 16-bit integer PCM. The format can't be opened by Processing but can be opened by audio applications.
    Parameters:
      `samples` - an array of floats in the audio range (-1.0f, 1.0f)
      `sampleRate` - the sample rate for the file
      `fileName` - name of the file
    Throws:
      `IOException` - an Exception you'll need to catch to call this method (see keyPressed entry for 's')

  - ### saveStereoAudioToFile

    public static void saveStereoAudioToFile(float[] leftChannel, float[] rightChannel, float sampleRate, String fileName) throws IOException, UnsupportedAudioFileException
    Saves stereo audio data to 16-bit integer PCM format, which Processing can also open.
    Parameters:
      `leftChannel` - an array of floats in the audio range (-1.0f, 1.0f)
      `rightChannel` - an array of floats in the audio range (-1.0f, 1.0f)
      `sampleRate` - audio sample rate for the file
      `fileName` - name of the file to save to
    Throws:
      `IOException` - an Exception you'll need to handle to call this method (see keyPressed entry for 's')
      `UnsupportedAudioFileException` - another Exception (see keyPressed entry for 's')

  - ### saveStereoAudioTo32BitPCMFile

    public static void saveStereoAudioTo32BitPCMFile(float[] leftChannel, float[] rightChannel, float sampleRate, String fileName) throws IOException
    Saves stereo audio data to a 32-bit floating point format that has higher resolution than 16-bit integer PCM. The format can't be opened by Processing but can be opened by audio applications.
    Parameters:
      `leftChannel` - an array of floats in the audio range (-1.0f, 1.0f)
      `rightChannel` - an array of floats in the audio range (-1.0f, 1.0f)
      `sampleRate` - the sample rate for the file
      `fileName` - name of the file
    Throws:
      `IOException` - an Exception you'll need to handle when calling this method