Blender V5.3
node_geo_sample_sound_frequencies.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2026 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#include "BKE_sound_sample.hh"
6
8
10
12
13enum class FFTSize {
14 _128 = 128,
15 _256 = 256,
16 _512 = 512,
17 _1024 = 1024,
18 _2048 = 2048,
19 _4096 = 4096,
20 _8192 = 8192,
21 _16384 = 16384,
22 _32768 = 32768,
23};
24
25enum class WindowFunction {
26 Hann = 0,
30};
31
33 {int(FFTSize::_128), "128", 0, "128", ""},
34 {int(FFTSize::_256), "256", 0, "256", ""},
35 {int(FFTSize::_512), "512", 0, "512", ""},
36 {int(FFTSize::_1024), "1024", 0, "1024", ""},
37 {int(FFTSize::_2048), "2048", 0, "2048", ""},
38 {int(FFTSize::_4096), "4096", 0, "4096", ""},
39 {int(FFTSize::_8192), "8192", 0, "8192", ""},
40 {int(FFTSize::_16384), "16384", 0, "16384", ""},
41 {int(FFTSize::_32768), "32768", 0, "32768", ""},
42 {},
43};
44
46 {int(WindowFunction::Hann), "Hann", 0, "Hann", ""},
47 {int(WindowFunction::Hamming), "Hamming", 0, "Hamming", ""},
48 {int(WindowFunction::Blackman), "Blackman", 0, "Blackman", ""},
50 "Rectangular",
51 0,
52 N_("Rectangular"),
53 N_("Equivalent to having no window function")},
54 {},
55};
56
58{
59 b.use_custom_socket_order();
60 b.allow_any_socket_order();
61
62 b.add_output<decl::Float>("Amplitude"_ustr)
63 .propagate_references()
64 .description("Sum of amplitudes of the frequencies in the given range")
65 .structure_type(StructureType::Dynamic);
66 b.add_input<decl::Sound>("Sound"_ustr).optional_label().description("Sound to sample");
67 b.add_input<decl::Float>("Time"_ustr)
68 .subtype(PROP_TIME_ABSOLUTE)
69 .structure_type(StructureType::Dynamic)
70 .description("Time in seconds of the sound to sample at");
71 b.add_input<decl::Bool>("All Channels"_ustr)
72 .default_value(true)
73 .structure_type(StructureType::Dynamic)
74 .description("Mix all channels before sampling the sound (e.g. stereo to mono)");
75 b.add_input<decl::Int>("Channel"_ustr)
76 .min(0)
77 .usage_inference(
78 [](const socket_usage_inference::SocketUsageParams &params) -> std::optional<bool> {
79 if (const std::optional<bool> any_output_used = params.any_output_is_used()) {
80 if (!*any_output_used) {
81 return false;
82 }
83 }
84 else {
85 return std::nullopt;
86 }
87 const std::optional<bool> all_channels =
88 params.get_input("All Channels"_ustr).get_if_primitive<bool>();
89 if (!all_channels.has_value()) {
90 return true;
91 }
92 return !*all_channels;
93 })
94 .structure_type(StructureType::Dynamic)
95 .description("The channel to sample unless 'All Channels' is checked");
96 b.add_input<decl::Float>("Low"_ustr)
97 .subtype(PROP_FREQUENCY)
98 .default_value(0.0f)
99 .min(0.0f)
100 .structure_type(StructureType::Dynamic)
101 .description("Lower bound of the sampled frequency range");
102 b.add_input<decl::Float>("High"_ustr)
103 .subtype(PROP_FREQUENCY)
104 .default_value(10'000.0f)
105 .min(0.0f)
106 .structure_type(StructureType::Dynamic)
107 .description("Upper bound of the sampled frequency range");
108
109 {
110 auto &p = b.add_panel("FFT"_ustr)
111 .default_closed(true)
112 .description("Configure details of the fourier transformation");
113 p.add_input<decl::Menu>("FFT Size"_ustr)
114 .static_items(fft_size_items)
116 .optional_label()
117 .description(
118 "Number of samples to process in the discrete fourier transformation at once. Higher "
119 "values have higher frequency but lower time resolution and vice versa");
120 p.add_input<decl::Menu>("Window Function"_ustr)
121 .static_items(window_function_items)
123 .optional_label()
124 .description(
125 "Applies a tapering function to the windowed samples to minimize discontinuities at "
126 "the edges, improving frequency resolution and reducing artifacts");
127 }
128}
129
130class SampleSoundFunction : public mf::MultiFunction {
131 private:
132 const bSound &sound_;
133 const int fft_size_;
134 const bke::bSoundFrequencySampler::WindowFunction window_function_;
135
136 public:
138 const int fft_size,
140 : sound_(sound), fft_size_(fft_size), window_function_(window_function)
141 {
142 static const mf::Signature signature = []() {
143 mf::Signature signature;
144 mf::SignatureBuilder builder("Sample Sound", signature);
145 builder.single_input<float>("Time");
146 builder.single_input<bool>("All Channels");
147 builder.single_input<int>("Channel");
148 builder.single_input<float>("Low");
149 builder.single_input<float>("High");
150 builder.single_output<float>("Amplitude");
151 return signature;
152 }();
153 this->set_signature(&signature);
154 BLI_assert(is_power_of_2(fft_size_));
155 }
156
157 void call(const IndexMask &mask, mf::Params params, mf::Context /*context*/) const override
158 {
159 const VArray<float> &times = params.readonly_single_input<float>(0, "Time");
160 const VArray<bool> &all_channels_varray = params.readonly_single_input<bool>(1,
161 "All Channels");
162 const VArray<int> &channels = params.readonly_single_input<int>(2, "Channel");
163 const VArray<float> &lows = params.readonly_single_input<float>(3, "Low");
164 const VArray<float> &highs = params.readonly_single_input<float>(4, "High");
165 MutableSpan<float> amplitudes = params.uninitialized_single_output<float>(5, "Amplitude");
166
167 const std::optional<bool> all_channels_value = all_channels_varray.get_if_single();
168 const std::optional<float> channel_value = channels.get_if_single();
169 const bool constant_channel = all_channels_value == true ||
170 (all_channels_value.has_value() && channel_value.has_value());
171
172 const auto time_interpolation = bke::bSoundFrequencySampler::InterpolationMethod::BSpline;
173 const auto frequency_interpolation = bke::bSoundFrequencySampler::InterpolationMethod::BSpline;
174
175 /* Optimize the case when all indices sample the same channel. */
176 if (constant_channel) {
178 key.window_function = window_function_;
179 key.fft_size = fft_size_;
180 key.channel = *all_channels_value ? std::nullopt : channel_value;
181 const std::shared_ptr<const bke::bSoundFrequencySampler> sampler =
183 if (!sampler) {
184 index_mask::masked_fill(amplitudes, 0.0f, mask);
185 return;
186 }
187 mask.foreach_index([&](const int i) {
188 const float time = times[i];
189 const float low = lows[i];
190 const float high = highs[i];
191 const float amplitude = sampler->sample(
192 time, low, high, time_interpolation, frequency_interpolation);
193 amplitudes[i] = amplitude;
194 });
195 return;
196 }
197
198 /* Sort indices by channel, optimizing for the common case that the channel number is typically
199 * very low. */
200 constexpr int channel_array_size = 6;
201 std::array<Vector<int>, channel_array_size> indices_by_channel;
202 MultiValueMap<int, int> indices_with_different_channel;
203 Vector<int> indices_with_all_channels;
204 mask.foreach_index([&](const int i) {
205 const bool all_channels = all_channels_varray[i];
206 if (all_channels) {
207 indices_with_all_channels.append(i);
208 }
209 else {
210 const int channel = channels[i];
211 if (channel >= 0 && channel < channel_array_size) {
212 indices_by_channel[channel].append(i);
213 }
214 else {
215 indices_with_different_channel.add(channel, i);
216 }
217 }
218 });
219
220 /* Actually sample the indices by channel. */
221 auto sample_indices_in_channel = [&](const Span<int> indices,
222 const std::optional<int> channel) {
223 if (indices.is_empty()) {
224 return;
225 }
227 key.window_function = window_function_;
228 key.fft_size = fft_size_;
229 key.channel = channel;
230 const std::shared_ptr<const bke::bSoundFrequencySampler> sampler =
232 if (!sampler) {
233 amplitudes.fill_indices(indices, 0.0f);
234 return;
235 }
236 for (const int i : indices) {
237 const float time = times[i];
238 const float low = lows[i];
239 const float high = highs[i];
240 const float amplitude = sampler->sample(
241 time, low, high, time_interpolation, frequency_interpolation);
242 amplitudes[i] = amplitude;
243 }
244 };
245
246 sample_indices_in_channel(indices_with_all_channels, std::nullopt);
247 for (const int channel : IndexRange(channel_array_size)) {
248 sample_indices_in_channel(indices_by_channel[channel], channel);
249 }
250 for (const auto item : indices_with_different_channel.items()) {
251 sample_indices_in_channel(item.value, item.key);
252 }
253 }
254};
255
256static int to_fft_size_int(const FFTSize fft_size)
257{
258 switch (fft_size) {
259 case FFTSize::_128:
260 return 128;
261 case FFTSize::_256:
262 return 256;
263 case FFTSize::_512:
264 return 512;
265 case FFTSize::_1024:
266 return 1024;
267 case FFTSize::_2048:
268 return 2048;
269 case FFTSize::_4096:
270 return 4096;
271 case FFTSize::_8192:
272 return 8192;
273 case FFTSize::_16384:
274 return 16384;
275 case FFTSize::_32768:
276 return 32768;
277 }
278 return 4096;
279}
280
296
298{
299 bSound *sound = params.extract_input<bSound *>("Sound"_ustr);
300 if (!sound) {
302 return;
303 }
304
305 const FFTSize fft_size = params.extract_input<FFTSize>("FFT Size"_ustr);
306 const WindowFunction window_function = params.extract_input<WindowFunction>(
307 "Window Function"_ustr);
308
309 SocketValueVariant times = params.extract_input<SocketValueVariant>("Time"_ustr);
310 SocketValueVariant all_channels = params.extract_input<SocketValueVariant>("All Channels"_ustr);
311 SocketValueVariant channels = params.extract_input<SocketValueVariant>("Channel"_ustr);
312 SocketValueVariant lows = params.extract_input<SocketValueVariant>("Low"_ustr);
313 SocketValueVariant highs = params.extract_input<SocketValueVariant>("High"_ustr);
314
315 auto sample_fn = std::make_shared<SampleSoundFunction>(
316 *sound, to_fft_size_int(fft_size), to_window_function(window_function));
317
318 SocketValueVariant amplitudes;
319 std::string error_message;
320 if (!execute_multi_function_on_value_variant(std::move(sample_fn),
321 {&times, &all_channels, &channels, &lows, &highs},
322 {&amplitudes},
323 params.user_data(),
324 error_message))
325 {
327 params.error_message_add(NodeWarningType::Error, std::move(error_message));
328 return;
329 }
330
331 params.set_output("Amplitude"_ustr, std::move(amplitudes));
332}
333
334static void node_register()
335{
336 static bke::bNodeType ntype;
337 geo_node_type_base(&ntype, "GeometryNodeSampleSoundFrequencies"_ustr);
338 ntype.ui_name = "Sample Sound Frequencies";
339 ntype.ui_description =
340 "Retrieve the amplitude from a sound data-block of a frequency range at a given time";
342 ntype.declare = node_declare;
346}
348
349} // namespace blender::nodes::node_geo_sample_sound_frequencies_cc
#define NODE_CLASS_CONVERTER
Definition BKE_node.hh:484
#define NOD_REGISTER_NODE(REGISTER_FUNC)
constexpr IndexRange()=default
MapType::ItemIterator items() const
void add(const Key &key, const Value &value)
constexpr bool is_empty() const
Definition BLI_span.hh:264
void append(const T &value)
static std::shared_ptr< const bSoundFrequencySampler > get_cached(const bSound &sound, const Key &key)
void set_signature(const Signature *signature)
void error_message_add(const NodeWarningType type, StringRef message) const
T extract_input(const UString identifier)
GeoNodesUserData * user_data() const
void set_output(const UString identifier, T &&value)
std::optional< T > get_if_primitive() const
void call(const IndexMask &mask, mf::Params params, mf::Context) const override
SampleSoundFunction(bSound &sound, const int fft_size, const bke::bSoundFrequencySampler::WindowFunction window_function)
#define sampler(slot)
void node_register_type(bNodeType &ntype)
Definition node.cc:2920
void masked_fill(MutableSpan< T > data, const T &value, const IndexMask &mask)
static bke::bSoundFrequencySampler::WindowFunction to_window_function(const WindowFunction window_function)
bool execute_multi_function_on_value_variant(const MultiFunction &fn, const std::shared_ptr< MultiFunction > &owned_fn, const Span< SocketValueVariant * > input_values, const Span< SocketValueVariant * > output_values, GeoNodesUserData *user_data, std::string &r_error_message)
BLI_assert(slot->slot_subtype.map==BMO_OP_SLOT_SUBTYPE_MAP_FLT)
constexpr int64_t is_power_of_2(const int64_t x)
@ PROP_TIME_ABSOLUTE
Definition RNA_types.hh:311
@ PROP_FREQUENCY
Definition RNA_types.hh:349
void geo_node_type_base(bke::bNodeType *ntype, UString idname, const std::optional< int16_t > legacy_type)
#define min(a, b)
Definition sort.cc:38
static constexpr int _180
Definition BKE_node.hh:247
Defines a node type.
Definition BKE_node.hh:265
std::string ui_description
Definition BKE_node.hh:271
NodeGeometryExecFunction geometry_node_execute
Definition BKE_node.hh:385
NodeDeclareFunction declare
Definition BKE_node.hh:393
#define N_(msgid)