swagger: '2.0' info: title: Signal Spectrum Analysis API description: >- Signal Spectrum Analysis API provides essential functionality for sound analysis, based on discrete Fourier transform. version: '3.0' x-released: no x-visibility: external schemes: - https basePath: /api/spectrumanalysis/v3 tags: - name: Fourier Transformation description: >- Provides Fourier Transform functionality for sound analysis. - name: Threshold Alert description: >- Performs amplitude breaching detection. Detects out of bounds frequency amplitudes inside a frequency range. securityDefinitions: spectrumAnalysis: type: oauth2 flow: accessCode authorizationUrl: 'https://oauth.simple.api/authorization' tokenUrl: 'https://oauth.simple.api/token' scopes: as.sa.fft: "Allows to call Spectrum Analysis service." paths: /calculateFrequencies: post: tags: - Fourier Transformation summary: Performs Fast Fourier transformation on a sound file. description: >- Decomposes the sound file into frequency components and returns the amplitude of each component. By default a FLATTOP window is applied before the Fourier transformation to help improve processing results. operationId: fftTransform security: - spectrumAnalysis: - as.sa.fft consumes: - multipart/form-data - audio/wav produces: - application/json parameters: - name: file in: formData type: file format: wav required: true description: >- The sound file that is transformed. If the sound is stereo then an average operation is made to obtain one channel. Supports up to 1MB input files and the file must be either 8 bits or 16 bits wav format. - name: fftProperties in: formData type: string format: json description: >- The input properties for the Short Time Fourier transformation processing.
- windowType - the type of window used for preprocessing input signal. The allowed values for window type are\: FLATTOP, HAMMING, HANNING and BLACKMAN. The input format for the paramater is a JSON string like the example below. For more details check the FFTProperties schema.
Format:
{ windowType: “FLATTOP” } responses: '200': description: OK schema: $ref: '#/definitions/FFTOutput' '400': description: Wrong parameters schema: type: object properties: errors: type: array items: $ref: "#/definitions/CalculateFrequenciesBadRequestError" default: description: Other error with any status code and response body format. /detectThresholdViolations: post: tags: - Threshold Alert summary: Performs detection of amplitudes for given thresholds. description: >- Detects Fourier Transformation components which breach given thresholds. (Either lower, upper thresholds or both) operationId: detectThresholdViolations security: - spectrumAnalysis: - as.sa.fft consumes: - application/json produces: - application/json parameters: - name: data in: body required: true schema: $ref: '#/definitions/ThresholdViolationInput' description: >- Data structure with two parts - data and spectrumFilter. - data - array of amplitudes of frequency components as returned by the Fourier Transformation. Conforms to data array from output of /calculateFrequencies. - spectrumFilter - represents a frequency interval and thresholds that, when breached, will be signalled in the response. You can specify either lower or upper thresholds, or both but at least one of the thresholds must be specified. responses: '200': description: OK schema: $ref: '#/definitions/ThresholdViolationOutput' '400': description: Wrong parameters schema: type: object properties: errors: type: array items: $ref: "#/definitions/DetectThresholdViolationsBadRequestError" default: description: Other error with any status code and response body format. definitions: FFTOutput: description: "Data model describing the Fourier Transformation result." type: object properties: data: description: "Object containg values of the amplitudes and corresponding value of maximum frequencies." type: object properties: maxFFTFrequency: type: number format: float description: >- Maximum value of the frequency from the Fourier Transformation result. example: 22050 amplitudes: type: array items: type: number format: float description: >- The array with the amplitudes from the Fourier Transformation result. example: [-225.81,-35.42,-36.66,-35.15,-40.27,-35.72,-38.73,-29.63,...,-27.35] numberOfFFTComponents: type: integer format: int32 description: >- Number of samples from the wav file. example: 111200 amplitudeUnit: type: string description: >- Measure unit for the Fourier Transformation result. example: "dB" FFTProperties: description: The input properties for the Fourier transformation processing. type: object properties: windowType: $ref: '#/definitions/WindowType' FFTData: description: "Input data resulted from a Fourier Transformation." type: object properties: maxFFTFrequency: type: number format: float description: >- Maximum value of the frequency from the Fourier Transformation result. minimum: 0 example: 22050 amplitudes: type: array items: type: number format: float description: >- The array with the amplitudes from the Fourier Transformation result. example: [-225.81,-35.42,-36.66,-35.15,-40.27,-35.72,-38.73,-29.63,...,-27.35] required: - maxFFTFrequency - amplitudes SpectrumFilter: type: object description: >- Contains the values of frequencies between which the detection is performed and the procesing limit and also the procesing thresholds that specify upper and/or lower limit for breaches to be detected. It is required to specify at least one of the thresholds. properties: minFrequency: type: number format: float minimum: 0 example: 51200 description: >- Lower limit of frequency band measured in Hz. maxFrequency: type: number format: float minimum: 0 example: 101200 description: >- Upper limit of frequency band measured in Hz. lowerThreshold: type: number format: float example: -40.25 description: >- Lower value of the threshold measured in db. upperThreshold: type: number format: float example: -20.25 description: >- Upper value of the threshold measured in db. ThresholdViolationInput: type: object description: >- Data model containing threshold alert input. properties: data: $ref: '#/definitions/FFTData' spectrumFilter: $ref: '#/definitions/SpectrumFilter' required: - data - spectrumFilter example: data: maxFFTFrequency: 22050 amplitudes: [-225.81,-35.42,-36.66,-35.15,-40.27,-35.72,-38.73,-29.63,...,-27.35] spectrumFilter: minFrequency: 51200 maxFrequency: 101200 lowerThreshold: -40.25 upperThreshold: -30.0 UpperDetection: type: object description: >- Data model describing the breaching of upper threshold. properties: frequencyAtMaxAmplitude: type: number format: float example: 61200 description: >- The frequency of the highest component. maxAmplitude: type: number format: float example: -40.27 description: >- The highest value detected. breachPercentage: type: number format: float minimum: 0 maximum: 100 example: 25.0 description: >- The percentage of components above the threshold within the frequency interval. LowerDetection: type: object description: >- Data model describing the breaching of lower threshold. properties: frequencyAtMinAmplitude: type: number format: float example: 61200 description: >- The frequency of the lowest component. minAmplitude: type: number format: float example: -40.27 description: >- The lowest value detected. breachPercentage: type: number format: float minimum: 0 maximum: 100 example: 25.0 description: >- The percentage of components below the threshold within the frequency interval. ThresholdViolationOutput: type: object description: Data model describing the Threshold Alert result. properties: upperDetection: $ref: '#/definitions/UpperDetection' lowerDetection: $ref: '#/definitions/LowerDetection' example: upperDetection: frequencyAtMaxAmplitude: 61200 maxAmplitude: -40.27 breachPercentage: 25.0 lowerDetection: frequencyAtMinAmplitude: 100200 minAmplitude: -27.35 breachPercentage: 50.0 WindowType: type: object properties: windowType: type: string description: >- The type of window used for preprocessing input signal. enum: - FLATTOP - HAMMING - HANNING - BLACKMAN example: FLATTOP default: FLATTOP CalculateFrequenciesBadRequestError: allOf: - $ref: '#/definitions/Error' type: object description: Server error properties: code: enum: - mdsp.core.spectrumanalysis.wrongWindowType - mdsp.core.spectrumanalysis.unsupportedFormat - mdsp.core.spectrumanalysis.wrongAudioFormat - mdsp.core.spectrumanalysis.invalidAudioFile - mdsp.core.spectrumanalysis.fileSizeExceeded example: mdsp.core.spectrumanalysis.wrongWindowType DetectThresholdViolationsBadRequestError: allOf: - $ref: '#/definitions/Error' type: object description: Server error properties: code: enum: - mdsp.core.spectrumanalysis.wrongFrequencyInterval - mdsp.core.spectrumanalysis.wrongAmplitudeInterval - mdsp.core.spectrumanalysis.missingThresholdValue - mdsp.core.spectrumanalysis.wrongMaxFrequencyValue example: "mdsp.core.spectrumanalysis.wrongFrequencyInterval" Error: type: object properties: code: type: string description: >- Platform wide unique error code. logref: type: string description: >- Log correlation id example: "30275fe58e6a4c7f956242d7a08d8ff3" message: type: string description: >- Short error message in English. example: "Field must not be null."