audiotree 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 David Braun
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,35 @@
1
+ Metadata-Version: 2.1
2
+ Name: audiotree
3
+ Version: 0.1.0
4
+ Summary: Audio data loading and augmentations in JAX
5
+ Home-page: https://github.com/DBraun/audiotree
6
+ Author: David Braun
7
+ Author-email: David Braun <braun@ccrma.stanford.edu>
8
+ Project-URL: Homepage, https://github.com/DBraun/audiotree
9
+ Project-URL: Issues, https://github.com/DBraun/audiotree/issues
10
+ Keywords: audio,machine learning
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Requires-Python: >=3.10
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: chex>=0.1.86
18
+ Requires-Dist: einops
19
+ Requires-Dist: flax>=0.8.2
20
+ Requires-Dist: grain==0.2.*
21
+ Requires-Dist: librosa>=0.10.1
22
+ Requires-Dist: numpy
23
+ Requires-Dist: soundfile
24
+ Requires-Dist: typing_extensions
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest; extra == "dev"
27
+ Requires-Dist: pytest-cov; extra == "dev"
28
+
29
+ # AudioTree
30
+
31
+ Audio data loading and augmentations in JAX.
32
+
33
+ ## Documentation
34
+
35
+ <https://dirt.design/audiotree>
@@ -0,0 +1,7 @@
1
+ # AudioTree
2
+
3
+ Audio data loading and augmentations in JAX.
4
+
5
+ ## Documentation
6
+
7
+ <https://dirt.design/audiotree>
@@ -0,0 +1,26 @@
1
+ [project]
2
+ name = "audiotree"
3
+ dynamic = ["version", "dependencies", "optional-dependencies"]
4
+ authors = [
5
+ { name="David Braun", email="braun@ccrma.stanford.edu" },
6
+ ]
7
+ description = "Audio data loading and augmentations in JAX"
8
+ readme = "README.md"
9
+ requires-python = ">=3.10"
10
+ classifiers = [
11
+ "Programming Language :: Python :: 3",
12
+ "License :: OSI Approved :: MIT License",
13
+ "Operating System :: OS Independent",
14
+ ]
15
+
16
+ keywords = [
17
+ "audio",
18
+ "machine learning",
19
+ ]
20
+
21
+ [project.urls]
22
+ Homepage = "https://github.com/DBraun/audiotree"
23
+ Issues = "https://github.com/DBraun/audiotree/issues"
24
+
25
+ [tool.setuptools.dynamic]
26
+ version = {attr = "audiotree.__version__"}
@@ -0,0 +1,45 @@
1
+ [metadata]
2
+ name = audiotree
3
+ version = attr: audiotree.__version__
4
+ url = https://github.com/DBraun/audiotree
5
+ author = David Braun
6
+ author_email = braun@ccrma.stanford.edu
7
+ description = Audio data loading and augmentations in JAX
8
+ long_description = file: README.md
9
+ long_description_content_type = "text/markdown"
10
+ classifiers =
11
+ Intended Audience :: Developers
12
+ Natural Language :: English
13
+ Programming Language :: Python :: 3.10
14
+ Programming Language :: Python :: 3.11
15
+ Programming Language :: Python :: 3.12
16
+ Topic :: Multimedia :: Sound/Audio
17
+ Topic :: Software Development :: Libraries
18
+
19
+ [options]
20
+ package_dir =
21
+ = src
22
+ packages = find:
23
+ python_requires = >=3.10
24
+ install_requires =
25
+ chex>=0.1.86
26
+ einops
27
+ flax>=0.8.2
28
+ grain==0.2.*
29
+ librosa>=0.10.1
30
+ numpy
31
+ soundfile
32
+ typing_extensions
33
+
34
+ [options.packages.find]
35
+ where = src
36
+
37
+ [options.extras_require]
38
+ dev =
39
+ pytest
40
+ pytest-cov
41
+
42
+ [egg_info]
43
+ tag_build =
44
+ tag_date = 0
45
+
@@ -0,0 +1,4 @@
1
+ __version__ = "0.1.0"
2
+ # Don't move the line above. It must be the first line due to `docs/source/conf.py`
3
+ from .core import AudioTree
4
+ from .core import SaliencyParams
@@ -0,0 +1,343 @@
1
+ from dataclasses import field
2
+ from functools import partial
3
+ from pathlib import Path
4
+ from typing import Callable, List, Union
5
+ from typing_extensions import Self
6
+
7
+ from flax import struct
8
+ from jax import numpy as jnp
9
+ import librosa
10
+ import numpy as np
11
+ import soundfile
12
+
13
+ from .loudness import jit_integrated_loudness
14
+ from .resample import resample
15
+
16
+
17
+ @struct.dataclass
18
+ class SaliencyParams:
19
+ """
20
+ The parameters for saliency detection.
21
+
22
+ Args:
23
+ enabled (bool): Whether to enable saliency detection.
24
+ num_tries (int): Maximum number of attempts to find a salient section of audio (default 8).
25
+ loudness_cutoff (float): Minimum loudness cutoff in decibels for determining salient audio (default -40).
26
+ search_function (Union[Callable, str]): The search function for determining the random offset. The default is
27
+ ``SaliencyParams.search_uniform``. Another option is ``SaliencyParams.search_bias_early`` which gradually
28
+ searches earlier in the file as more attempts are made.
29
+ """
30
+
31
+ enabled: bool = field(default=False)
32
+ num_tries: int = 8
33
+ loudness_cutoff: float = -40
34
+
35
+ # Note: Although Union[Callable, str] would be a better type annotation, it doesn't work well with argbind
36
+ search_function: str = "SaliencyParams.search_uniform"
37
+
38
+ @staticmethod
39
+ def search_uniform(
40
+ rng: np.random.Generator,
41
+ offset: float,
42
+ duration: float,
43
+ total_duration: float,
44
+ attempt: int,
45
+ max_attempts: int,
46
+ ):
47
+ lower_bound = max(0.0, offset)
48
+ upper_bound = max(total_duration - duration, lower_bound)
49
+ return rng.uniform(lower_bound, upper_bound)
50
+
51
+ @staticmethod
52
+ def search_bias_early(
53
+ rng: np.random.Generator,
54
+ offset: float,
55
+ duration: float,
56
+ total_duration: float,
57
+ attempt: int,
58
+ max_attempts: int,
59
+ ):
60
+ lower_bound = max(0.0, offset)
61
+ upper_bound1 = max(total_duration - duration, lower_bound)
62
+ # linearly interpolate the upper bound based on number of attempts so far
63
+ alpha = attempt / (max_attempts - 1) if max_attempts > 1 else 0
64
+ upper_bound2 = min(upper_bound1, lower_bound + duration)
65
+ upper_bound = upper_bound1 * (1 - alpha) + upper_bound2 * alpha
66
+ return rng.uniform(lower_bound, upper_bound)
67
+
68
+
69
+ _str_max_length = 256
70
+
71
+
72
+ @struct.dataclass
73
+ class AudioTree:
74
+ """
75
+ A `flax.struct.dataclass`_ for holding audio information including a waveform, sample rate, and metadata.
76
+
77
+ The ``AudioTree`` class is inspired by Descript AudioTools's `AudioSignal`_.
78
+ .. _AudioSignal: https://github.com/descriptinc/audiotools/blob/master/audiotools/core/audio_signal.py
79
+ .. _flax.struct.dataclass: https://flax.readthedocs.io/en/latest/api_reference/flax.struct.html#flax.struct.dataclass
80
+
81
+ Args:
82
+ audio_data (jnp.ndarray): Audio waveform data in JAX numpy tensor shaped ``(Batch, Channels, Samples)``
83
+ sample_rate (int): Sample rate of ``audio_data``, such as 44100 Hz.
84
+ loudness (float, optional): Loudness of the audio waveform in LUFs. Don't set this when initializing. Instead,
85
+ use ``replace_loudness()`` to create a new AudioTree with ``loudness`` calculated.
86
+ pitch (float, optional): The MIDI pitch where 60 is middle C.
87
+ velocity (float, optional): The MIDI velocity between 0 and 127.
88
+ duration (float, optional): The duration of the audio waveform in seconds.
89
+ codes (jnp.ndarray): The neural audio codec tokens for the audio.
90
+ metadata (dict): Any extra metadata can be placed here.
91
+ """
92
+
93
+ audio_data: jnp.ndarray
94
+ sample_rate: int = struct.field(pytree_node=False)
95
+ loudness: float = None
96
+ pitch: float = None
97
+ velocity: float = None
98
+ duration: float = None
99
+ codes: jnp.ndarray = None
100
+ metadata: dict = struct.field(pytree_node=True, default_factory=dict)
101
+
102
+ def replace_loudness(self) -> Self:
103
+ """Replace ``loudness`` property with a JAX scalar."""
104
+ loudness = jit_integrated_loudness(self.audio_data, self.sample_rate, zeros=512)
105
+ return self.replace(loudness=loudness)
106
+
107
+ @staticmethod
108
+ def _encode_string(s: str):
109
+ # Convert string to list of ASCII values and pad with 0
110
+ encoded = [ord(char) for char in s] + [0] * (_str_max_length - len(s))
111
+ return jnp.array([encoded]) # [1, _str_max_length]
112
+
113
+ @staticmethod
114
+ def _decode_string(encoded_array: jnp.ndarray):
115
+ # Convert list of integers to characters and join them into a string
116
+ decoded = "".join([chr(val) for val in encoded_array if val != 0])
117
+ return decoded
118
+
119
+ @property
120
+ def filepath(self) -> List[str]:
121
+ """Return a list of filepaths assuming information exists in ``metadata['filepath']]``"""
122
+ return [self._decode_string(data) for data in self.metadata["filepath"]]
123
+
124
+ @classmethod
125
+ def from_file(
126
+ cls,
127
+ audio_path: str,
128
+ sample_rate: int = None,
129
+ offset: float = 0.0,
130
+ duration: float = None,
131
+ mono: bool = False,
132
+ cpu: bool = False,
133
+ ):
134
+ """Create an AudioTree from an audio file path.
135
+
136
+ Args:
137
+ audio_path (str): Path to audio file.
138
+ sample_rate (int, optional): Sample rate of audio data, such as 44100 Hz. If left as ``None``, the file's
139
+ original sample rate will be used.
140
+ offset (float, optional): Offset in seconds to audio data.
141
+ duration (float, optional): Duration in seconds of audio data. The audio data will be trimmed or extended as
142
+ necessary.
143
+ mono (bool, optional): Whether to force the audio data to be single-channel.
144
+
145
+ Returns:
146
+ AudioTree: An instance of ``AudioTree``.
147
+ """
148
+ data, sr = librosa.load(
149
+ audio_path, sr=sample_rate, offset=offset, duration=duration, mono=mono
150
+ )
151
+ assert sr == sample_rate
152
+ if data.ndim == 1:
153
+ data = data[None, None, :] # Add batch and channel dimension
154
+ elif data.ndim == 2:
155
+ data = data[None, :, :] # Add batch dimension
156
+
157
+ if duration is not None and data.shape[-1] < round(duration * sample_rate):
158
+ pad_right = round(duration * sample_rate) - data.shape[-1]
159
+ data = np.pad(data, ((0, 0), (0, 0), (0, pad_right)))
160
+
161
+ if not cpu:
162
+ data = jnp.array(data, dtype=jnp.float32)
163
+
164
+ return cls(
165
+ audio_data=data,
166
+ sample_rate=sr,
167
+ metadata={
168
+ "filepath": cls._encode_string(audio_path),
169
+ "offset": offset,
170
+ "duration": duration,
171
+ },
172
+ )
173
+
174
+ @classmethod
175
+ def from_array(cls, audio_data: np.ndarray, sample_rate: int) -> Self:
176
+ """Create an AudioTree from an audio array and a sample rate.
177
+
178
+ Args:
179
+ audio_data (jnp.ndarray): Audio data shaped ``(Batch, Channels, Samples)``
180
+ sample_rate (int): Sample rate of audio data, such as 44100 Hz.
181
+
182
+ Returns:
183
+ AudioTree: An instance of ``AudioTree``.
184
+ """
185
+ audio_data = jnp.array(audio_data, dtype=jnp.float32)
186
+ if audio_data.ndim == 1:
187
+ audio_data = audio_data[None, None, :] # Add batch and channel dimension
188
+ elif audio_data.ndim == 2:
189
+ audio_data = audio_data[None, :, :] # Add batch dimension
190
+ return cls(audio_data=audio_data, sample_rate=sample_rate)
191
+
192
+ @classmethod
193
+ def excerpt(
194
+ cls,
195
+ audio_path: str,
196
+ rng: np.random.Generator,
197
+ offset: float = 0.0,
198
+ duration: float = None,
199
+ search_function: Callable = None,
200
+ **kwargs,
201
+ ) -> Self:
202
+ """Create an AudioTree from a random section of audio from a file path.
203
+
204
+ Args:
205
+ audio_path (str): Path to audio file.
206
+ rng (np.random.Generator): Random number generator.
207
+ offset (float, optional): Offset in seconds to audio data.
208
+ duration (float, optional): Duration in seconds of audio data. The audio data will be trimmed or lengthened
209
+ as necessary.
210
+ search_function (Callable, optional): A function that determines the random offset.
211
+ **kwargs: Keyword arguments passed to ``AudioTree.__init__``.
212
+
213
+ Returns:
214
+ AudioTree: An instance of ``AudioTree``.
215
+ """
216
+ assert duration is not None and duration > 0
217
+ info = soundfile.info(audio_path)
218
+ total_duration = info.duration # seconds
219
+
220
+ if search_function is None:
221
+ search_function = partial(
222
+ SaliencyParams.search_uniform, attempts=0, max_attempts=1
223
+ )
224
+
225
+ random_offset = search_function(rng, offset, duration, total_duration)
226
+
227
+ audio_signal = cls.from_file(
228
+ audio_path=audio_path, offset=random_offset, duration=duration, **kwargs
229
+ )
230
+
231
+ return audio_signal
232
+
233
+ @classmethod
234
+ def salient_excerpt(
235
+ cls,
236
+ audio_path: Union[str, Path],
237
+ rng: np.random.Generator,
238
+ saliency_params: SaliencyParams,
239
+ **kwargs,
240
+ ) -> Self:
241
+ """Create an AudioTree from a salient section of audio from a file path.
242
+
243
+ Args:
244
+ audio_path (str): Path to audio file.
245
+ rng (np.random.Generator): Random number generator such as ``np.random.default_rng(42)``.
246
+ saliency_params (SaliencyParams): Saliency parameters to use to find a salient section.
247
+ **kwargs: Keyword arguments passed to ``AudioTree.__init__``.
248
+
249
+ Returns:
250
+ AudioTree: An instance of ``AudioTree``.
251
+ """
252
+ assert (
253
+ "offset" not in kwargs
254
+ ), "``salient_excerpt`` cannot be used with kwarg ``offset``."
255
+ assert (
256
+ "duration" in kwargs
257
+ ), "``salient_excerpt`` must be used with kwarg ``duration``."
258
+ if (
259
+ not saliency_params.enabled
260
+ or saliency_params.loudness_cutoff is None
261
+ or np.isnan(saliency_params.loudness_cutoff)
262
+ ):
263
+ excerpt = cls.excerpt(audio_path, rng=rng, **kwargs)
264
+ else:
265
+ loudness = -np.inf
266
+ current_try = 0
267
+ num_tries = saliency_params.num_tries
268
+ if isinstance(saliency_params.search_function, str):
269
+ _search_function = eval(saliency_params.search_function)
270
+ else:
271
+ _search_function = saliency_params.search_function
272
+ while loudness <= saliency_params.loudness_cutoff:
273
+ search_function = partial(
274
+ _search_function,
275
+ attempt=current_try,
276
+ max_attempts=num_tries,
277
+ )
278
+ new_excerpt = cls.excerpt(
279
+ audio_path, rng=rng, search_function=search_function, **kwargs
280
+ ).replace_loudness()
281
+ if current_try == 0 or new_excerpt.loudness > loudness:
282
+ excerpt = new_excerpt
283
+ loudness = new_excerpt.loudness
284
+ current_try += 1
285
+ if num_tries is not None and current_try >= num_tries:
286
+ break
287
+ return excerpt
288
+
289
+ def to_mono(self) -> Self:
290
+ """Reduce the ``audio_data`` to mono.
291
+
292
+ Returns:
293
+ AudioTree: An instance of ``AudioTree``.
294
+ """
295
+ audio_data = self.audio_data.mean(axis=1, keepdims=True)
296
+ return self.replace(audio_data=audio_data, loudness=None)
297
+
298
+ def resample(
299
+ self,
300
+ sample_rate: int,
301
+ zeros: int = 24,
302
+ rolloff: float = 0.945,
303
+ output_length: int = None,
304
+ full: bool = False,
305
+ ) -> Self:
306
+ """
307
+ Resample the AudioTree's ``audio_data`` to a new sample rate. The algorithm is a JAX port of ``ResampleFrac``
308
+ from the PyTorch library `Julius`_.
309
+
310
+ .. _Julius: https://github.com/adefossez/julius/blob/main/julius/resample.py
311
+
312
+ Args:
313
+ sample_rate (int): The new sample rate of audio data, such as 44100 Hz.
314
+ zeros (int, optional): number of zero crossing to keep in the sinc filter.
315
+ rolloff (float): use a lowpass filter that is ``rolloff * sample_rate / 2``,
316
+ to ensure sufficient margin due to the imperfection of the FIR filter used.
317
+ Lowering this value will reduce antialiasing, but will reduce some of the
318
+ highest frequencies.
319
+ output_length (None or int): This can be set to the desired output length (last dimension).
320
+ Allowed values are between 0 and ``ceil(length * sample_rate / old_sr)``. When ``None`` (default) is
321
+ specified, the floored output length will be used. In order to select the largest possible
322
+ size, use the `full` argument.
323
+ full (bool): return the longest possible output from the input. This can be useful
324
+ if you chain resampling operations, and want to give the ``output_length`` only
325
+ for the last one, while passing ``full=True`` to all the other ones.
326
+
327
+ Returns:
328
+ AudioTree: An instance of ``AudioTree``.
329
+ """
330
+ if sample_rate == self.sample_rate:
331
+ return self
332
+ audio_data = resample(
333
+ self.audio_data,
334
+ self.sample_rate,
335
+ sample_rate,
336
+ zeros=zeros,
337
+ rolloff=rolloff,
338
+ output_length=output_length,
339
+ full=full,
340
+ )
341
+ return self.replace(
342
+ audio_data=audio_data, sample_rate=sample_rate, loudness=None
343
+ )
@@ -0,0 +1,3 @@
1
+ from .core import AudioDataSourceMixin
2
+ from .core import AudioDataBalancedSource
3
+ from .core import AudioDataSimpleSource