Audio engine post-processing on STM32F4xx Graphical Equalizer
Contents
1. ci UM1798 WI life augmented User manual Audio engine post processing on STM32F4xx Graphical Equalizer library Introduction This document reviews the software interface and requirements of the Graphic Equalizer GrEQ module All necessary interface functions parameters integration constraints for the programmer to integrate the GrEQ library STM32 AUDIO100A into his own software are described in this document The GrEQ library is designed to run on an ARM Cortex M4 core without FPU usage so it can be integrated and run on all the STM32F40xxx STM32F41xxx STM32F42xxx or STM32F43xxx products September 2014 DoclD026640 Rev 1 1 19 www st com Contents UM1798 Contents 1 Module overview rule pRREXBARERERERERA SROCRAENWENEAEG ce EERE 5 1 1 Algorithm functionality uctus irn dee cian dec pe cee e REOR cd eR e Une 5 1 2 Module configuration 2 06 aaa AA a Rh n 5 1 3 Resources summary 0 lll 5 2 Module interfaces 22 22 EARLIER BALAAN RP TS ES 6 2 1 APIS pre i rnaak TIT 6 2 1 1 Function greq reset aaae 6 2 1 2 Function greq setParam naana anana 6 2 1 3 Function greq getParam selsseeee ee 7 2 1 4 Function greq setConfig e ee eee 7 2 1 5 Function greq getConfig eee 8 2 1 6 Function greg process ees 8 2 2 External definitions and types a 8 2 2 1 Input and output buffers liliis 8 2 2 2 Returned error values2. 3 Rock Figure 3 4 Vocal Figure 4 5 Classical Figure 5 6 HipHop Figure 6 DoclD026640 Rev 1 11 19 UM1798 Algorithm description Figure 1 Frequency response for Pop music GrEQ PReset Pop e a c c a e gp apnpubew Frequency Hz Figure 2 Frequency response for Jazz music reset Jazz qP GrE e a c c a e x e gp apnyubew 5 Frequency Hz DoclD026640 Rev 1 12 19 Algorithm description UM1798 Figure 3 Frequency response for Rock music Rock GrEQ Preset e a Z c a e gp apnyubew Frequency Hz Figure 4 Frequency response for Vocal music reset Vocal P GrEQ e a c c a e e gp pnpubew 5 Frequency Hz 13 19 DoclD026640 Rev 1 UM1798 Algorithm description Figure 5 Frequency response for Classical music Classical GrEQ Preset e a Z c a e gp apnyubew Frequency Hz Figure 6 Frequency response for Hip Hop music HipHop GrEQ Preset e o aoc com c a Ado ao gp pnpubew Frequency Hz DoclD026640 Rev 1 14 19 UM1798 Application Description 4 4 1 a Application Description Recommendations for Optimal Setup The GrEQ module can be executed at any place in an audio processing chain because it applies a linear algorithm there is no restriction on the order of
3. It handles static parameters i e the parameter values that cannot be changed during module processing int32 t greq setParam greq static param t input static param ptr void static mem ptr Table 4 Parameters for function greq getParam I O Name Type Description Input input_static_param_ptr greq_static_param_t Pointer to static parameters structure Input static mem ptr void Pointer to internal static memory Returned int32 t Error value value 3 Function greq setConfig This procedure sets module dynamic parameters from main framework to module internal memory It can be called at any time during processing int32 t greq setConfig greq dynamic param t input dynamic param ptr void static mem ptr Table 5 Parameters for function greq setConfig y o Name Type Description x Pointer to dynamic parameters Input input dynamic param ptr greq dynamic param t structure Input static mem ptr void Pointer to internal static memory Returned int32_t Error value value DoclD026640 Rev 1 7 19 Module interfaces UM1798 2 1 5 2 1 6 2 2 2 2 1 8 19 Function greq getConfig This procedure gets the module dynamic parameters from internal static memory to the main framework It can be called at any time during processing int32 t greq getConfig greq dynamic param t input dynamic param ptr void static mem ptr
4. Table 6 Parameters for function greq getConfig 1 0 Name Type Description x Pointer to dynamic parameters Input input dynamic param ptr greq dynamic param t structure Input static mem ptr void Pointer to internal static memory Retumed int32_t Error value value Function greq_process This procedure is the module s main processing routine It should be called at any time to process each frame int32 t greq process buffer t input buffer buffer t output buffer void static mem ptr Table 7 Parameters for function greq process 1 0 Name Type Description Input input_buffer buffer t Pointer to input buffer structure Output output buffer buffer t Pointer to output buffer structure Input static mem ptr void Pointer to internal static memory Output int32 t Error value This routine can run in place meaning that the same buffer can be used for input and output External definitions and types Input and output buffers The GrEQ library uses extended I O buffers which contain in addition to the samples some useful information on the stream such as the number of channels the number of bytes per sample and the interleaving mode d DoclD026640 Rev 1 UM1798 Module interfaces An I O buffer structure type as described below must be respected each time before calling the processing routine else errors will be returned typed
5. UM1798 2 3 Static parameters structure The GrEQ initial parameters are set using the corresponding static parameter structure before calling the greq setParam function struct greq static param intl6 t nb bands Table 10 nb bands parameter Name Type Description nb bands Center frequencies 5 125 400 1278 4088 13074 nb bands intte_t Defines the number 8 100 203 412 837 1698 3447 6998 14206 of bands 5 8 or 10 10 62 115 214 399 742 1380 2567 4775 8882 16520 2 4 Dynamic parameters structure It is possible to change the GrEQ configuration by setting new values in the dynamic parameter structure before calling the greq setConfig function struct greq dynamic param intl6 t enable intl6 t user gain per band dB int16 t gain preset idx Table 11 Dynamic parameters Name Type Description 0 disable the effect output buffer is equal to input buffer enable int16 t 1 enable the effect output buffer is equal to input buffer processed by GrEQ Sets the gain for each band user gain per band dB 10 int16 t The values are specified in dB iini go from 12 to 12dB in 1dB steps Depending on the nb bands static parameter value see Table 10 only values 5 8 or 10 can be selected GrEQ library is configured with 6 gain presets When the user selects one preset the gains in the user gain per band dB table are discarded 0 no preset
6. ess 9 2 3 Static parameters structure llle 10 2 4 Dynamic parameters structure iles 10 3 Algorithm description 0443 a pagg KERI RR NSK EDEN NADA AKEN 11 3 1 Processing steps taka AA dti the aa are rac AUR ns osa a t dia a aues 11 3 2 Data formats ii s rasta cx ees RR nae katy Re CNRC a ace es 11 3 2 1 Preset frequency responses 000 e cence eee eee 11 4 Application Description 00 cece eee 15 4 1 Recommendations for Optimal Setup 2 20005 15 4 1 1 Memory allocation 0 0 cece eee 15 4 1 2 Module APIs calls vase e444 RE RR REA REG E 15 5 How to tune and run the application LL 17 6 Revision history case akan E RR RO RERLID AA x Y EEErERRERR 18 2 19 DocID026640 Rev 1 Ly UM1798 List of tables List of tables Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 3 SUMMary Of TESOUICES EC 5 Parameters for function greq reset 00 0 e eee eee eee 6 Parameters for function greq setParam llli 6 Parameters for function greq getParam cece eee 7 Parameters for function greq setConfig 000 cee eee ee 7 Parameters for function greq getConfig aeae 8 Parameters for function greq process elles 8 Input and output buffers 20 0 0 eee 9 Error values usos hp NG Ee EY Rue San veh ee
7. the choice selection and use of ST products and ST assumes no liability for application assistance or the design of Purchasers products No license express or implied to any intellectual property right is granted by ST herein Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product ST and the ST logo are trademarks of ST All other product or service names are the property of their respective owners Information in this document supersedes and replaces information previously supplied in any prior versions of this document 2014 STMicroelectronics All rights reserved d DoclD026640 Rev 1 19 19
8. use the gains in the user gain per band dB table 1 Pop gain preset idx int16 t 2 Jazz 3 Rock 4 Vocal 5 Classical 6 HipHop 10 19 DoclD026640 Rev 1 d UM1798 Algorithm description 3 3 1 3 2 3 2 1 d Algorithm description Processing steps The GrEQ algorithm is based on the parallelization of band pass filters BPFs The BPFs are characterized by their center frequencies and Q factor Depending on the number of bands 5 8 or 10 the center frequencies and Q factor are set so that BPFs cover the audible spectrum with each center frequency equally spaced on a logarithmic scale The GrEQ embeds a special processing which reduce drastically the neighboring effect of a band on the others Each band gain can thus be set quasi independently from the others Each BPF is implemented using an optimized bi quadratic structure using 32 bits coefficients Data formats Input of GrEQ module is expected to be an audio stream stereo interleaved in 16 or 32 bits format All operations are done with 32 bits resolution The output format is an audio stream stereo interleaved signal in 16 or 32 bits format Preset frequency responses The frequency responses for each music style are shown in dedicated figures as summarized in Table 12 Table 12 Frequency responses for different presets Preset Music style Frequency response 1 Pop Figure 1 2 Jazz Figure 2
9. am write New Config needed greq setConfig Samples to proceed Memory freeing MS35660V1 16 19 DoclD026640 Rev 1 Ly UM1798 How to tune and run the application 5 How to tune and run the application The STM32 audio framework provides an example application for the GrEQ library It uses the library with 10 bands and typically implements 10 sliders which allow gain adjustment for each band It also proposes a list box for selecting one of the six presets Tuning of the GrEQ depends entirely on the loudspeaker user preference and music style There is no real recommendation for tuning DoclD026640 Rev 1 17 19 3 Revision history UM1798 6 18 19 Revision history Table 13 Document revision history Date 30 Sep 2014 Revision 1 Initial release Changes DoclD026640 Rev 1 d UM1798 IMPORTANT NOTICE PLEASE READ CAREFULLY STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections enhancements modifications and improvements to ST products and or to this document at any time without notice Purchasers should obtain the latest relevant information on ST products before placing orders ST products are sold pursuant to ST s terms and conditions of sale in place at the time of order acknowledgement Purchasers are solely responsible for
10. d PC eae RAT de 9 nb bands parameter lll 10 Dynamic parameters 2 10 Frequency responses for different presets 00 ce eee eee eee 11 Document revision history ee eee 18 DoclD026640 Rev 1 3 19 List of figures UM1798 List of figures Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 4 19 Frequency response for Pop music cece eee eee eee eee 12 Frequency response for Jazz music 000 es 12 Frequency response for Rock music llli 13 Frequency response for Vocal music 000 eee eee 13 Frequency response for Classical music llle 14 Frequency response for Hip Hop music liliis 14 Sequence of APIS o ks Rene a uy Vea p nte E Gee e Hd gon ec d ka 16 DoclD026640 Rev 1 3 UM1798 Module overview 1 1 1 2 1 3 d Module overview Algorithm functionality The GraphicEQualizer GrEQ module is in charge of fine tuning the sound spectrum according to user personal preferences This is done by modifying gain factors at fixed frequencies represented by sliders The number of bands is determined at the initialization phase and can be 5 8 or 10 The gain factors are adjustable from 12dB to 12dB in standard mode The library can be generated with different maximum gains 18dB 24dB The current implementation uses 32 bits resolution for all computations and can be used with both 16 and 32 b
11. ef struct int32 t int32 t void int32 t int32 t nb channels nb bytes per Sample data ptr buffer t buffer size mode Table 8 Input and output buffers Name Type Description Number of channels in data b ch I int32 t E nee 1 for mono 2 for stereo 4 for 3 1 multichannel Dynamic of data in number of bytes NA AYES por sample Jatd iS biis 2 24 bis c3 32 bite 4 data ptr void Pointer to data buffer must be allocated by the main framework buffer size int32 t Number of samples per channel in the data buffer In case of stereo stream left and right channels can be interleaved mode int32 t 0 not interleaved 1 interleaved 2 2 2 Returned error values Table 9 lists possible returned error values Table 9 Error values Definition Value Description GREQ_ERROR_NONE 0 No error GREQ_UNSUPPORTED_NB OF BYTEPERSAMPLES 1 Input data is not 16 bit sample format GREQ UNSUPPORTED NB CHANNELS 2 Input data is neither mono nor stereo GREQ UNSUPPORTED NB OF BANDS 3 Number of bands not supported GREQ UNSUPPORTED GAIN PRESET 4 Gain preset index not supported GREQ UNSUPPORTED INTERLEAVING MODE 5 Input data is stereo not interleaved GREQ UNSUPPORTED FRAME SIZE 6 Frame size not supported GREQ UNSUPPORTED GAIN 7 Gain not supported GREQ BAD HW 8 Unsupported HW for the library d DoclD026640 Rev 1 9 19 Module interfaces
12. execution However care should be taken in the gain distribution all over the processing chain as the GrEQ applies pre attenuation At the input of the GrEQ some margin is taken in order to avoid any saturation when the user is setting positive gains The default available library is generated with a maximum gain of 12dB as a consequence 2 bits of guard are taken Memory allocation The static and dynamic parameters structures must be allocated Their types are defined in greq glo h header Example of allocation parameters structure memory allocation greq static param t static param ptr malloc sizeof greq static param t greq dynamic param t dynamic param ptr malloc sizeof greq dynamic param t The static and dynamic memory pointer must be allocated too The size of each is defined in greq glo h header Example of allocation memory structure memory allocation void static mem ptr malloc greq static mem size void dynamic mem ptr malloc greq dynamic mem size It is then needed to allocate the memory for input and output audio buffers Module APIs calls The sequence is shown in Figure 7 and each step is described in detail in the following list 1 As explained above GrEQ static and dynamic structures have to be allocated as well as input and output buffer accordingly to the structures defined in Section 2 2 1 2 Once memory has been allocated the call to greq reset function will i
13. its input output format Module configuration GrEQ module supports Mono and Stereo interleaved 16 or 32 bits I O data with a maximum input frame size of 480 stereo samples This limitation corresponds to 10ms scheduling at 48 kHz sampling frequency Resources summary Table 1 contains CPU Flash Stack and RAM requirements The core MHz value is an estimation based on IAR systems v6 50 simulation profiling Table 1 Summary of resources Flash code Flash data text rodata Stack Static RAM Dynamic RAM CPU frequency Stereo interleaved 48 kHz 4344 Bytes 8 Bytes 92 Bytes 548 Bytes 3840 Bytes 14 5 MHz DoclD026640 Rev 1 5 19 Module interfaces UM1798 2 Module interfaces Two files are needed to integrate the GrEQ module lib greq md4 a library supports 16 bits I O data while lib greq m4 32b a library supports 32 bits I O data greq glo h header file contains all definitions and structures to be exported to the application SW Note also that audio fw glo h file is a generic header file common to all audio modules and must be included in the audio framework 2 1 APIs Six generic functions have a software interface to the main program they allow the developer to initialize reset set or get parameters and process audio buffers 2 1 1 Function greq reset This procedure initializes the static memory of the Graphical Equalizer module and initializes static parameter
14. nitialize internal variables 3 The GrEQ configuration for the desired filter response can now be set by initializing the static param structure 4 Calling the greq setParam function will then configure the GrEQ internal memory according to the desired number of bands 5 Then the gains per band or the preset can be changed by setting the dynamic parameters structure and calling greg setConfig function 6 Theaudio stream is read from the proper interface and input buffer structure has to be filled according to the stream characteristics number of channels sample rate interleaving and data pointer Output buffer structure has to be set as well 7 Calling the greq process function will execute the GrEQ algorithm 8 The output audio stream can now be written in the proper interface 9 f needed the user can set new dynamic parameters and call the greq setConfig function to update module configuration DoclD026640 Rev 1 15 19 Application Description UM1798 10 If the application is still running and has new input samples to proceed then it goes back to step 6 else the processing loop is over 11 Once the processing loop is over allocated memory has to be freed Figure 7 Sequence of APIs Memory allocation i greq reset i static param inizialization i greq setParam i greq setConfig Y 6 Audio stream read input buffer preparation i greq process i Audio stre
15. s with default values int32 t greq reset void static mem ptr void dynamic mem ptr Table 2 Parameters for function greq reset yo Name Type Description Input static mem ptr void Pointer to internal static memory Input dynamic mem ptr void Pointer to internal dynamic memory Returned value int32 t Error value This routine must be called at least once at initialization time when the real time processing has not yet started 2 1 2 Function greq setParam This procedure writes module s static parameters from the main framework to the module internal memory It can be called after reset routine and before real time processing start It handles static parameters i e the parameter values cannot be changed during the module processing int32 t greq setParam greq static param t input static param ptr void static mem ptr Table 3 Parameters for function greq setParam yo Name Type Description Input input static param ptr greq static param t Pointer to static parameters structure Input static mem ptr void Pointer to internal static memory Retumed int32_t Error value value 6 19 DoclD026640 Rev 1 Ly UM1798 Module interfaces 2 1 3 2 1 4 d Function greq getParam This procedure gets the module s static parameters from the module s internal memory to main framework It can be called after reset routine and before real time processing started
Download Pdf Manuals
Related Search