Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Documentation updates to ASRC

  • Loading branch information...
commit e2b6d354169c5d1ceced33d0731c6f18161f3b68 1 parent a568830
Henk Muller henkmuller authored

Showing 2 changed files with 42 additions and 28 deletions. Show diff stats Hide diff stats

  1. +33 20 doc/asrc.rst
  2. +9 8 module_asrc/src/asrc.h
53 doc/asrc.rst
Source Rendered
@@ -2,9 +2,10 @@ module_asrc
2 2 ...........
3 3
4 4 The Asynchronous Sample Rate converter is capable of deleting or inserting
5   -samples in arbitrary places in the input stream. This operation introduces
6   -harmoic distortion, but can be used when two asynchronous clocks provide
7   -data that must be kept in sync.
  5 +samples in arbitrary places in the input stream. This operation can be used
  6 +when an incoming signal has to be synchronised with a local clock.
  7 +By nature this operation introduces harmonic distortion that can be
  8 +minimised by setting the filter to a high upsampling rate and high order.
8 9
9 10 API
10 11 ---
@@ -15,25 +16,37 @@ Configuration defines
15 16
16 17 **ASRC_ORDER**
17 18
18   - This sets the number of samples over which to smooth the signal. The
19   - filter will be sqaure that size. Higher values create less audible
20   - artifacts, but increase latency in the signal, and increase
21   - computational requirements; both linear.
  19 + This sets the number of samples over which to smooth the signal. A
  20 + higher value creates less audible artifacts, but increases latency and
  21 + computational requirements linearly.
22 22
23 23 **ASRC_UPSAMPLING**
24 24
25 25 This sets the number of steps over which the lost/added sample is
26   - generated. The higher the value, the lower the noise floor. However,
27   - higher valus require more memory (the coefficient array is of size
  26 + generated. The filter can only insert or delete a sample once during
  27 + the upsampling period. The higher the value, the lower the noise floor.
  28 + Higher values require more memory (the coefficient array is of size
28 29 ASRC_ORDER * ASRC_UPSAMPLING), and it reduces the number of samples
29 30 that can be inserted or deleted.
30 31
31 32
32 33 The default values for ``ASRC_ORDER`` and ``ASRC_UPSAMPLING`` are 8
33   -and 125. At present, the only other combination supported is 8 and 64. In
34   -order to support other combinations, compute the coefficients for a
  34 +and 125. For each combination a table of coefficients is required. Tables
  35 +are defined as part of the module (in ``coeffs.xc``) for the following combinations:
  36 +
  37 +* 4 and 125
  38 +
  39 +* 4 and 250
  40 +
  41 +* 8 and 64
  42 +
  43 +* 8 and 125
  44 +
  45 +* 16 and 64
  46 +
  47 +To support other combinations, compute the coefficients for a
35 48 low-pass FIR filter (using the ``makefir`` program in this repo) with the
36   -following properties:
  49 +following parameters:
37 50
38 51 * Corner frequency: -low 24000
39 52
@@ -44,9 +57,9 @@ following properties:
44 57 * Scale value: -one ``16777216 * ASRC_UPSAMPLING``
45 58
46 59 Delete the second half of the generated values, (the filter will be
47   -symmetrical) so that you are left with
48   -``(ASRC_UPSAMPLING * ASRC_ORDER)/2 + 1``
49   -coefficients, and so that the last value of the array is ``16777216``.
  60 +symmetrical) so that you are left with ``(ASRC_UPSAMPLING * ASRC_ORDER)/2 +
  61 +1`` coefficients, and so that the last value of the array is ``16777216``.
  62 +Add this array to an appropriate ``#elif`` in ``coeffs.xc``
50 63
51 64 Types
52 65 '''''
@@ -92,17 +105,17 @@ call to the filter function (to delete a sample), this takes 170 thread
92 105 cycles or 3.4 us at 50 MIPS. This worst case is guaranteed to happen
93 106 only once per deleted sample, and typical performance when filtering is 110 thread cycles or
94 107 2.2 us at 50 MIPS. Hence, if this function is called just prior to
95   -delivering an audio sample in a 48 KHz stream, then a single thread at 50
96   -MIPS can filter around 6 streams at 48 KHz, or 3 streams at 96 KHz. If used
97   -in a system with a small buffer, 9 streams can be processed.
  108 +delivering an audio sample in a 48 kHz stream, then a single thread at 50
  109 +MIPS can filter around 6 streams at 48 kHz, or 3 streams at 96 kHz. If used
  110 +in a system with a small buffer, 9 streams can be processed at 48 kHz.
98 111
99 112 Distortion
100 113 ''''''''''
101 114
102   -Below we show the frequency analysyis of a 1KHz sinewave that has been
  115 +Below we show the frequency analysyis of a 1kHz sinewave that has been
103 116 slowed down or sped up using the Asynchronous Sample Rate converter with
104 117 upsampling rates of between 64 and 250, and filters of orders 4, 8, and 16.
105   -This experiment used a 48 KHz sample rate at 24 bits. Note that order 16
  118 +This experiment used a 48 kHz sample rate at 24 bits. Note that order 16
106 119 does not make a significant difference; for many applications order 4 or 8
107 120 will be sufficient.
108 121
17 module_asrc/src/asrc.h
@@ -18,7 +18,7 @@
18 18 #elif (ASRC_ORDER == 16)
19 19 #define ASRC_ARRAY 32
20 20 #else
21   -#error "Undefined ASRC_ORDER, set to 8 or 16"
  21 +#error "Undefined ASRC_ORDER, set to 4, 8 or 16"
22 22 #endif
23 23
24 24 /** Structure that is used to store the state of the converter. One
@@ -36,7 +36,8 @@ struct asrcState {
36 36 };
37 37
38 38 /** Function that initialises the asynchronous sample rate converter. This
39   - * resets the state.
  39 + * resets the state and should be called once for each ``struct acrcState``
  40 + * declared.
40 41 *
41 42 * \param state buffer structure containing past sample values for
42 43 * interpolation
@@ -47,8 +48,8 @@ void asrcInit(struct asrcState &state);
47 48 * called on every sample. Set the parameter ``diff`` to -1 or +1 to
48 49 * indicate that a sample is to be deleted or inserted. Anytime that this
49 50 * function is called with a request to delete or insert a sample, at least
50   - * ASRC_UPSAMPLING calls should be made with ``diff`` set to 0 for the
51   - * signal to stabilise.
  51 + * ASRC_UPSAMPLING+1 calls should be made with ``diff`` set to 0 for the
  52 + * interpolation to complete.
52 53 *
53 54 * When ``diff`` is -1, the return value of the function should be ignored,
54 55 * this accounts for the deleted sample. When ``diff`` is +1, the input
@@ -57,15 +58,15 @@ void asrcInit(struct asrcState &state);
57 58 *
58 59 * \param sample current sample value. Ignored if ``diff`` is +1.
59 60 *
60   - * \param diff value to indicate that a sample shall be deleted or inserted
  61 + * \param diff value to indicate that a sample shall be deleted or inserted
61 62 * from the stream. When -1, a value shall be deleted and the
62 63 * return value of this function should be ignored. When +1 a
63 64 * value shall be inserted into the stream, and the sample
64 65 * passed into the function will be ignored.
65 66 *
66   - * \param state buffer structure containing past sample values for
67   - * interpolation
  67 + * \param state buffer structure containing past sample values for
  68 + * interpolation
68 69 *
69   - * \returns an interpolated sample value. To be ifnored if ``diff`` is -1.
  70 + * \returns an interpolated sample value. To be ignored if ``diff`` is -1.
70 71 */
71 72 int asrcFilter(int sample, int diff, struct asrcState &state);

0 comments on commit e2b6d35

Please sign in to comment.
Something went wrong with that request. Please try again.