* Use GitHub's Jekyll static site generator. * Move all documentation to docs/ directory. * Convert HTML to Markdown.
Showing the changes to docs/api_simple.md (1 of 38 files). Show all
Unified · Split
| @@ -0,0 +1,71 @@ | ||
| 1 | +--- | |
| 2 | +layout: default | |
| 3 | +--- | |
| 4 | + | |
| 5 | +# Simple API | |
| 6 | + | |
| 7 | +**Important Note:** The simple API is not designed to work on small chunks of a | |
| 8 | +larger piece of audio. If you attempt to use it this way you are doing it wrong | |
| 9 | +and will not get the results you want. For processing audio data in chunks you | |
| 10 | +**must** use the [full api](api_full.md) or the [callback based api](api_callback.md). | |
| 11 | + | |
| 12 | +The simple API consists of a single function: | |
| 13 | + | |
| 14 | +```c | |
| 15 | +int src_simple (SRC_DATA *data, int converter_type, int channels) ; | |
| 16 | +``` | |
| 17 | + | |
| 18 | +The use of this function rather than the more fully featured API requires the | |
| 19 | +caller to know the total length of the input data before hand and that all input | |
| 20 | +and output data can be held in the system's memory at once. It also assumes that | |
| 21 | +there is a single constant ratio between input and output sample rates. | |
| 22 | + | |
| 23 | +Dealing with the easy stuff first, the **converter_type** parameter should be | |
| 24 | +one of the values defined in **samplerate.h** and documented [here](api_misc.md#converters) | |
| 25 | +while the **channels** parameter specifies the number of interleaved channels | |
| 26 | +that the sample rate converter is being asked to process (number of input | |
| 27 | +channels and output channels is always equal). There is no hard upper limit on | |
| 28 | +the number of channels; it is limited purely by the amount of memory available. | |
| 29 | + | |
| 30 | +The first parameter to **src_simple** is a pointer to an **SRC_DATA** struct | |
| 31 | +(more info [here](api_misc.md#src_data)) defined as follows: | |
| 32 | + | |
| 33 | +```c | |
| 34 | +typedef struct | |
| 35 | +{ const float *data_in; | |
| 36 | + float *data_out ; | |
| 37 | + | |
| 38 | + long input_frames, output_frames ; | |
| 39 | + long input_frames_used, output_frames_gen ; | |
| 40 | + | |
| 41 | + int end_of_input ; | |
| 42 | + | |
| 43 | + double src_ratio ; | |
| 44 | +} SRC_DATA ; | |
| 45 | +``` | |
| 46 | + | |
| 47 | +The fields of this struct which must be filled in by the caller are: | |
| 48 | + | |
| 49 | +data_in | |
| 50 | +: A pointer to the input data samples. | |
| 51 | + | |
| 52 | +input_frames | |
| 53 | +: The number of frames of data pointed to by data_in. | |
| 54 | + | |
| 55 | +data_out | |
| 56 | +: A pointer to the output data samples. | |
| 57 | + | |
| 58 | +output_frames | |
| 59 | +: Maximum number of frames pointer to by data_out. | |
| 60 | + | |
| 61 | +src_ratio | |
| 62 | +: Equal to output_sample_rate / input_sample_rate. | |
| 63 | + | |
| 64 | +When the **src_simple** function returns **output_frames_gen** will be set to | |
| 65 | +the number of output frames generated and **input_frames_used** will be set to | |
| 66 | +the number of input frames used to generate the provided number of output | |
| 67 | +frames. | |
| 68 | + | |
| 69 | +The **src_simple** function returns a non-zero value when an error occurs. See | |
| 70 | +[here](api_misc.md#error-reporting) for how to convert the error value into a | |
| 71 | +text string. | |