MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Resample.hpp
Go to the documentation of this file.
1#pragma once
2
3/**
4 * @file Resample.hpp
5 * @brief Anti-aliased sample rate conversion by a rational ratio for MayaFlux::Kinesis
6 *
7 * Pure numerical functions on contiguous double-precision spans. Domain-agnostic:
8 * a sequence is resampled by the ratio of two rates, whatever it holds.
9 */
10
12
13/**
14 * @struct ResampleConfig
15 * @brief Design of the anti-aliasing filter of resample
16 *
17 * The filter is a windowed sinc whose cutoff is the lower of the two Nyquist
18 * frequencies. zero_crossings is the number of zero crossings of the sinc kept on
19 * each side of its centre, so a larger value narrows the transition band and
20 * lengthens the filter. kaiser_beta shapes the Kaiser window: a larger value
21 * lowers the stopband ripple and widens the transition band.
22 */
24 uint32_t zero_crossings { 10 };
25 double kaiser_beta { 5.0 };
26};
27
28/**
29 * @brief Number of samples resample returns
30 * @param samples Input length
31 * @param from_rate Rate of the input
32 * @param to_rate Rate of the output
33 * @return ceil(samples * to_rate / from_rate), 0 when either rate is 0
34 */
35[[nodiscard]] MAYAFLUX_API size_t resampled_length(
36 size_t samples, uint32_t from_rate, uint32_t to_rate) noexcept;
37
38/**
39 * @brief Resample a sequence from one rate to another with an anti-aliasing filter
40 *
41 * The ratio is reduced to up / down by its greatest common divisor and applied as
42 * a polyphase filter: the sequence is conceptually upsampled by up, lowpass
43 * filtered at the lower of the two Nyquist frequencies, and decimated by down,
44 * without computing the samples in between. Output sample k is at time
45 * k / to_rate and the filter delay is removed, so the first output sample lines
46 * up with the first input sample. Samples outside the input are zero. The same
47 * rates return a copy. Output blocks are computed in parallel.
48 *
49 * The result matches scipy.signal.resample_poly with a Kaiser window of the same
50 * beta and a filter half length of zero_crossings * max(up, down) samples.
51 *
52 * @param src Input samples
53 * @param from_rate Rate of the input in Hz
54 * @param to_rate Rate of the output in Hz
55 * @param config Anti-aliasing filter design
56 * @return resampled_length(src.size(), from_rate, to_rate) samples, empty when
57 * the input is empty or either rate is 0
58 */
59[[nodiscard]] MAYAFLUX_API std::vector<double> resample(
60 std::span<const double> src,
61 uint32_t from_rate,
62 uint32_t to_rate,
63 const ResampleConfig& config = {});
64
65/**
66 * @class Resampler
67 * @brief resample as a stream: block by block, with the filter history kept between calls
68 *
69 * Concatenating everything push returns and then flush returns gives exactly
70 * what resample returns for the concatenated input, however the input was cut
71 * into blocks, so no block edge restarts the filter. An output sample is
72 * produced as soon as the input samples it reads have arrived: each reads
73 * lookahead() input samples past its own time, which is the delay a live
74 * caller sees. flush ends the stream, supplying zeros past the last sample
75 * as resample does, and the next push starts a new stream. Equal rates pass
76 * the input through unchanged and with no delay.
77 *
78 * Only the input the next output still needs is retained, so memory is the
79 * length of the filter however long the stream runs. Not for concurrent use.
80 */
81class MAYAFLUX_API Resampler {
82public:
83 /**
84 * @brief Construct a resampler
85 * @param from_rate Rate of the input in Hz
86 * @param to_rate Rate of the output in Hz
87 * @param config Anti-aliasing filter design, as for resample
88 * @throws std::invalid_argument When either rate is 0
89 */
90 Resampler(uint32_t from_rate, uint32_t to_rate, const ResampleConfig& config = {});
92
93 Resampler(const Resampler&) = delete;
94 Resampler& operator=(const Resampler&) = delete;
95 Resampler(Resampler&&) noexcept;
96 Resampler& operator=(Resampler&&) noexcept;
97
98 /**
99 * @brief Continue the stream with more input
100 * @return The output samples that are complete, possibly none
101 */
102 [[nodiscard]] std::vector<double> push(std::span<const double> src);
103
104 /**
105 * @brief End the stream
106 * @return The remaining output samples, so that the stream's total is resampled_length of its input
107 */
108 [[nodiscard]] std::vector<double> flush();
109
110 /** @brief Start a new stream without releasing anything. */
111 void reset() noexcept;
112
113 /** @brief Input samples an output reads beyond its own time, 0 for equal rates. */
114 [[nodiscard]] size_t lookahead() const noexcept;
115
116 /** @brief Input samples currently held. */
117 [[nodiscard]] size_t retained() const noexcept;
118
119private:
120 struct Impl;
121 std::unique_ptr<Impl> m_impl;
122};
123
124} // namespace MayaFlux::Kinesis::Discrete
size_t retained() const noexcept
Input samples currently held.
Definition Resample.cpp:270
void reset() noexcept
Start a new stream without releasing anything.
Definition Resample.cpp:260
std::vector< double > flush()
End the stream.
Definition Resample.cpp:249
std::vector< double > push(std::span< const double > src)
Continue the stream with more input.
Definition Resample.cpp:234
Resampler(const Resampler &)=delete
Resampler(uint32_t from_rate, uint32_t to_rate, const ResampleConfig &config={})
Construct a resampler.
Definition Resample.cpp:208
size_t lookahead() const noexcept
Input samples an output reads beyond its own time, 0 for equal rates.
Definition Resample.cpp:265
Resampler & operator=(const Resampler &)=delete
std::vector< double > resample(std::span< const double > src, uint32_t from_rate, uint32_t to_rate, const ResampleConfig &config)
Resample a sequence from one rate to another with an anti-aliasing filter.
Definition Resample.cpp:135
size_t resampled_length(size_t samples, uint32_t from_rate, uint32_t to_rate) noexcept
Number of samples resample returns.
Definition Resample.cpp:126
Design of the anti-aliasing filter of resample.
Definition Resample.hpp:23