audiotree 0.0.5__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,41 @@
1
+ Metadata-Version: 2.1
2
+ Name: audiotree
3
+ Version: 0.0.5
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.1.0
21
+ Requires-Dist: librosa>=0.10.1
22
+ Requires-Dist: numpy
23
+ Requires-Dist: soundfile
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest; extra == "dev"
26
+ Requires-Dist: pytest-cov; extra == "dev"
27
+
28
+ # AudioTree
29
+
30
+ Audio data loading and augmentations in JAX.
31
+
32
+ ## Installation
33
+
34
+ ```bash
35
+ pip install audiotree
36
+ ```
37
+
38
+ ## Documentation
39
+
40
+ <https://dirt.design/audiotree>
41
+
@@ -0,0 +1,14 @@
1
+ # AudioTree
2
+
3
+ Audio data loading and augmentations in JAX.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install audiotree
9
+ ```
10
+
11
+ ## Documentation
12
+
13
+ <https://dirt.design/audiotree>
14
+
@@ -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,44 @@
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.1.0
29
+ librosa>=0.10.1
30
+ numpy
31
+ soundfile
32
+
33
+ [options.packages.find]
34
+ where = src
35
+
36
+ [options.extras_require]
37
+ dev =
38
+ pytest
39
+ pytest-cov
40
+
41
+ [egg_info]
42
+ tag_build =
43
+ tag_date = 0
44
+
@@ -0,0 +1,3 @@
1
+ __version__ = "0.0.5"
2
+
3
+ from .core import AudioTree
@@ -0,0 +1,206 @@
1
+ from pathlib import Path
2
+ from typing import Union
3
+
4
+ from flax import struct
5
+ from jax import numpy as jnp
6
+ import librosa
7
+ import numpy as np
8
+ import soundfile
9
+
10
+ from .loudness import jit_integrated_loudness
11
+ from .resample import resample
12
+
13
+
14
+ @struct.dataclass
15
+ class AudioTree:
16
+ """A ``flax.struct.dataclass`` for holding audio information including a waveform, sample rate, and metadata.
17
+
18
+ The ``AudioTree`` class is inspired by Descript AudioTools's `AudioSignal`_.
19
+ .. _AudioSignal: https://github.com/descriptinc/audiotools/blob/master/audiotools/core/audio_signal.py
20
+
21
+ Args:
22
+ audio_data (jnp.ndarray): Audio waveform data in JAX numpy tensor shaped (Batch, Channels, Time)
23
+ sample_rate (int): Sample rate of audio_data, such as 44100 Hz.
24
+ loudness (float, optional): Loudness of the audio waveform in LUFs. Don't set this when initializing. Instead,
25
+ use ``replace_loudness()`` to create a new AudioTree with ``loudness`` calculated.
26
+ pitch (float, optional): The MIDI pitch where 60 is middle C.
27
+ velocity (float, optional): The MIDI velocity between 0 and 127.
28
+ duration (float, optional): The duration of the audio waveform in seconds.
29
+ codes (jnp.ndarray): The neural audio codec tokens for the audio.
30
+ metadata (dict): Any extra metadata can be placed here.
31
+ """
32
+
33
+ audio_data: jnp.ndarray
34
+ sample_rate: int = struct.field(pytree_node=False)
35
+ loudness: float = None
36
+ pitch: float = None
37
+ velocity: float = None
38
+ duration: float = None
39
+ codes: jnp.ndarray = None
40
+ metadata: dict = struct.field(pytree_node=True, default_factory=dict)
41
+
42
+ def replace_loudness(self):
43
+ """Replace ``loudness`` property with a JAX scalar."""
44
+ loudness = jit_integrated_loudness(self.audio_data, self.sample_rate, zeros=512)
45
+ return self.replace(loudness=loudness)
46
+
47
+ @classmethod
48
+ def from_file(
49
+ cls,
50
+ audio_path: str,
51
+ sample_rate: int = None,
52
+ offset: float = 0,
53
+ duration: float = None,
54
+ mono: bool = False,
55
+ ):
56
+ """Create an AudioTree from an audio file path.
57
+
58
+ Args:
59
+ audio_path (str): Path to audio file.
60
+ sample_rate (int, optional): Sample rate of audio data, such as 44100 Hz. If left as ``None``, the file's
61
+ original sample rate will be used.
62
+ offset (float, optional): Offset in seconds to audio data.
63
+ duration (float, optional): Duration in seconds of audio data. The audio data will be trimmed or extended as
64
+ necessary.
65
+ mono (bool, optional): Whether to force the audio data to be single-channel.
66
+ """
67
+ data, sr = librosa.load(
68
+ audio_path, sr=sample_rate, offset=offset, duration=duration, mono=mono
69
+ )
70
+ assert sr == sample_rate
71
+ data = jnp.array(data, dtype=jnp.float32)
72
+ if data.ndim == 1:
73
+ data = data[None, None, :] # Add batch and channel dimension
74
+ elif data.ndim == 2:
75
+ data = data[None, :, :] # Add batch dimension
76
+
77
+ if duration is not None and data.shape[-1] < round(duration * sample_rate):
78
+ pad_right = round(duration * sample_rate) - data.shape[-1]
79
+ data = jnp.pad(data, ((0, 0), (0, 0), (0, pad_right)))
80
+
81
+ return cls(
82
+ audio_data=data,
83
+ sample_rate=sr,
84
+ metadata={"offset": offset, "duration": duration},
85
+ )
86
+
87
+ @classmethod
88
+ def from_array(cls, audio_data: np.ndarray, sample_rate: int):
89
+ """Create an AudioTree from an audio array and a sample rate.
90
+
91
+ Args:
92
+ audio_data (jnp.ndarray): Audio data shaped (Batch, Channels, Time)
93
+ sample_rate (int): Sample rate of audio data, such as 44100 Hz.
94
+ """
95
+ audio_data = jnp.array(audio_data, dtype=jnp.float32)
96
+ if audio_data.ndim == 1:
97
+ audio_data = audio_data[None, None, :] # Add batch and channel dimension
98
+ elif audio_data.ndim == 2:
99
+ audio_data = audio_data[None, :, :] # Add batch dimension
100
+ return cls(audio_data=audio_data, sample_rate=sample_rate)
101
+
102
+ @classmethod
103
+ def excerpt(
104
+ cls,
105
+ audio_path: str,
106
+ rng: np.random.RandomState,
107
+ offset: float = None,
108
+ duration: float = None,
109
+ **kwargs,
110
+ ):
111
+ assert duration is not None and duration > 0
112
+ info = soundfile.info(audio_path)
113
+ total_duration = info.duration # seconds
114
+
115
+ lower_bound = 0 if offset is None else offset
116
+ upper_bound = max(total_duration - duration, 0)
117
+ offset = rng.uniform(lower_bound, upper_bound)
118
+
119
+ audio_signal = cls.from_file(
120
+ audio_path=audio_path, offset=offset, duration=duration, **kwargs
121
+ )
122
+
123
+ return audio_signal
124
+
125
+ @classmethod
126
+ def salient_excerpt(
127
+ cls,
128
+ audio_path: Union[str, Path],
129
+ rng: np.random.RandomState,
130
+ loudness_cutoff: float = None,
131
+ num_tries: int = 8,
132
+ **kwargs,
133
+ ):
134
+ assert (
135
+ "offset" not in kwargs
136
+ ), "``salient_excerpt`` cannot be used with kwarg ``offset``."
137
+ assert (
138
+ "duration" in kwargs
139
+ ), "``salient_excerpt`` must be used with kwarg ``duration``."
140
+ if loudness_cutoff is None:
141
+ excerpt = cls.excerpt(audio_path, rng=rng, **kwargs)
142
+ else:
143
+ loudness = -np.inf
144
+ current_try = 0
145
+ while loudness <= loudness_cutoff:
146
+ current_try += 1
147
+ new_excerpt = cls.excerpt(
148
+ audio_path, rng=rng, **kwargs
149
+ ).replace_loudness()
150
+ if current_try == 1 or new_excerpt.loudness > loudness:
151
+ excerpt = new_excerpt
152
+ loudness = new_excerpt.loudness
153
+ if num_tries is not None and current_try >= num_tries:
154
+ break
155
+ return excerpt
156
+
157
+ def to_mono(self):
158
+ """
159
+ Reduce the ``audio_data`` to mono.
160
+ """
161
+ audio_data = jnp.mean(self.audio_data, axis=1, keepdims=True)
162
+ return self.replace(audio_data=audio_data, loudness=None)
163
+
164
+ def resample(
165
+ self,
166
+ sample_rate: int,
167
+ zeros: int = 24,
168
+ rolloff: float = 0.945,
169
+ output_length: int = None,
170
+ full: bool = False,
171
+ ):
172
+ """
173
+ Resample the AudioTree's ``audio_data`` to a new sample rate. The algorithm is a JAX port of ``ResampleFrac``
174
+ from the PyTorch library `Julius`_.
175
+
176
+ .. _Julius: https://github.com/adefossez/julius/blob/main/julius/resample.py
177
+
178
+ Args:
179
+ sample_rate (int): The new sample rate of audio data, such as 44100 Hz.
180
+ zeros (int, optional): number of zero crossing to keep in the sinc filter.
181
+ rolloff (float): use a lowpass filter that is ``rolloff * sample_rate / 2``,
182
+ to ensure sufficient margin due to the imperfection of the FIR filter used.
183
+ Lowering this value will reduce antialiasing, but will reduce some of the
184
+ highest frequencies.
185
+ output_length (None or int): This can be set to the desired output length (last dimension).
186
+ Allowed values are between 0 and ``ceil(length * sample_rate / old_sr)``. When None (default) is
187
+ specified, the floored output length will be used. In order to select the largest possible
188
+ size, use the `full` argument.
189
+ full (bool): return the longest possible output from the input. This can be useful
190
+ if you chain resampling operations, and want to give the ``output_length`` only
191
+ for the last one, while passing ``full=True`` to all the other ones.
192
+ """
193
+ if sample_rate == self.sample_rate:
194
+ return self
195
+ audio_data = resample(
196
+ self.audio_data,
197
+ self.sample_rate,
198
+ sample_rate,
199
+ zeros=zeros,
200
+ rolloff=rolloff,
201
+ output_length=output_length,
202
+ full=full,
203
+ )
204
+ return self.replace(
205
+ audio_data=audio_data, sample_rate=sample_rate, loudness=None
206
+ )
@@ -0,0 +1,4 @@
1
+ from .core import AudioDataSourceMixin
2
+ from .core import AudioDataBalancedSource
3
+ from .core import AudioDataSimpleSource
4
+ from .core import SaliencyParams
@@ -0,0 +1,217 @@
1
+ from dataclasses import field
2
+ import os
3
+ from random import Random
4
+ from typing import AnyStr, List, Mapping, SupportsIndex
5
+
6
+ from flax import struct
7
+ from grain import python as grain
8
+ import numpy as np
9
+
10
+ from audiotree import AudioTree
11
+
12
+ _default_extensions = [".wav", ".flac"]
13
+
14
+
15
+ @struct.dataclass
16
+ class SaliencyParams:
17
+ """
18
+ The parameters for saliency detection.
19
+
20
+ Args:
21
+ enabled (bool): Whether to enable saliency detection.
22
+ num_tries (int): Maximum number of attempts to find a salient section of audio (default 8).
23
+ loudness_cutoff (float): Minimum loudness cutoff in decibels for determining salient audio (default -40).
24
+ """
25
+ enabled: bool = field(default=False)
26
+ num_tries: int = 8
27
+ loudness_cutoff: float = -40
28
+
29
+
30
+ def _find_files_with_extensions(
31
+ directory: str, extensions: List[str], max_depth=None, follow_symlinks=False
32
+ ) -> list[AnyStr]:
33
+ """
34
+ Searches for files with specified extensions up to a maximum depth in the directory,
35
+ without modifying dirs while iterating.
36
+
37
+ Parameters:
38
+ - directory (str): The path to the directory to search.
39
+ - extensions (list): A list of file extensions to search for. Each extension should include a period.
40
+ - max_depth (int): The maximum depth to search for files.
41
+ - follow_symlinks (bool): Whether to follow symbolic links during the search.
42
+
43
+ Returns:
44
+ - list: A list of paths to files that match the extensions within the maximum depth.
45
+ """
46
+ matching_files = []
47
+ extensions_set = {
48
+ ext.lower() for ext in extensions
49
+ } # Normalize extensions to lowercase for matching
50
+
51
+ # Expand environment variables and user home directory
52
+ directory = os.path.expandvars(os.path.expanduser(directory))
53
+ directory = os.path.abspath(directory) # Ensure the directory path is absolute
54
+
55
+ def recurse(current_dir, current_depth):
56
+ if max_depth is not None and current_depth > max_depth:
57
+ return
58
+ with os.scandir(current_dir) as it:
59
+ for entry in it:
60
+ if entry.is_file(follow_symlinks=follow_symlinks) and any(
61
+ entry.name.lower().endswith(ext) for ext in extensions_set
62
+ ):
63
+ matching_files.append(entry.path)
64
+ elif entry.is_dir(follow_symlinks=follow_symlinks):
65
+ recurse(entry.path, current_depth + 1)
66
+
67
+ recurse(directory, 0)
68
+ return matching_files
69
+
70
+
71
+ class AudioDataSourceMixin:
72
+
73
+ def load_audio(self, file_path, record_key: SupportsIndex) -> AudioTree:
74
+
75
+ if self.saliency_params is not None and self.saliency_params.enabled:
76
+ saliency_params = self.saliency_params
77
+ return AudioTree.salient_excerpt(
78
+ file_path,
79
+ np.random.RandomState(int(record_key)),
80
+ loudness_cutoff=saliency_params.loudness_cutoff,
81
+ num_tries=saliency_params.num_tries,
82
+ sample_rate=self.sample_rate,
83
+ duration=self.duration,
84
+ mono=self.mono,
85
+ )
86
+
87
+ return AudioTree.from_file(
88
+ file_path,
89
+ sample_rate=self.sample_rate,
90
+ offset=0,
91
+ duration=self.duration,
92
+ mono=self.mono,
93
+ )
94
+
95
+
96
+ class AudioDataSimpleSource(grain.RandomAccessDataSource, AudioDataSourceMixin):
97
+
98
+ def __init__(
99
+ self,
100
+ sources: Mapping[str, List[str]],
101
+ sample_rate: int = 44100,
102
+ mono: int = 1,
103
+ duration: float = 1.0,
104
+ extensions: List[str] = None,
105
+ num_steps: int = None,
106
+ saliency_params: SaliencyParams = None,
107
+ ):
108
+
109
+ self.sample_rate = sample_rate
110
+ self.mono = bool(mono)
111
+ self.duration = duration
112
+ if extensions is None:
113
+ extensions = _default_extensions
114
+ self.saliency_params = saliency_params
115
+
116
+ filepaths = []
117
+ for group_name, folders in sources.items():
118
+ filepaths_in_group = []
119
+ for folder in folders:
120
+ filepaths_in_group += _find_files_with_extensions(
121
+ folder, extensions=extensions
122
+ )
123
+
124
+ if filepaths_in_group:
125
+ filepaths += filepaths_in_group
126
+ else:
127
+ raise RuntimeError(
128
+ f"Group '{group_name}' is empty. "
129
+ f"The number of specified folders in the group was {len(folders)}. "
130
+ f"The approved file extensions were {extensions}."
131
+ )
132
+
133
+ if num_steps is not None:
134
+ filepaths = filepaths[:num_steps]
135
+
136
+ self._file_paths = filepaths
137
+
138
+ self._length = len(filepaths)
139
+ assert self._length > 0
140
+
141
+ def __len__(self) -> int:
142
+ return self._length
143
+
144
+ def __getitem__(self, record_key: SupportsIndex):
145
+ file_path = self._file_paths[record_key]
146
+ return self.load_audio(file_path, record_key)
147
+
148
+
149
+ class AudioDataBalancedSource(grain.RandomAccessDataSource, AudioDataSourceMixin):
150
+
151
+ # todo: make this algorithm work if the user specifies weights for the groups.
152
+ # Right now the groups are balanced uniformly.
153
+ # Eventually the __init__ should just take a list of ``AudioDataSimpleSource`` and
154
+ # the corresponding weights.
155
+
156
+ def __init__(
157
+ self,
158
+ sources: Mapping[str, List[str]],
159
+ num_steps: int,
160
+ sample_rate: int = 44100,
161
+ mono: int = 1,
162
+ duration: float = 1.0,
163
+ extensions: List[str] = None,
164
+ saliency_params: SaliencyParams = None,
165
+ ):
166
+
167
+ self.sample_rate = sample_rate
168
+ self.mono = bool(mono)
169
+ self.duration = duration
170
+ if extensions is None:
171
+ extensions = _default_extensions
172
+ self.saliency_params = saliency_params
173
+
174
+ groups = []
175
+
176
+ for group_name, folders in sources.items():
177
+ filepaths = []
178
+ for folder in folders:
179
+ filepaths += _find_files_with_extensions(folder, extensions=extensions)
180
+
181
+ if filepaths:
182
+ groups.append(filepaths)
183
+ else:
184
+ raise RuntimeError(
185
+ f"Group '{group_name}' is empty. "
186
+ f"The number of specified folders in the group was {len(folders)}. "
187
+ f"The approved file extensions were {extensions}."
188
+ )
189
+
190
+ self._group_to_len = {i: len(group) for i, group in enumerate(groups)}
191
+ self._groups = groups
192
+ self._num_groups = len(groups)
193
+ self._length = num_steps
194
+ assert self._length > 0
195
+
196
+ def __len__(self) -> int:
197
+ return self._length
198
+
199
+ def __getitem__(self, record_key: SupportsIndex):
200
+ record_key = int(record_key)
201
+
202
+ group_idx = record_key % self._num_groups
203
+
204
+ idx = record_key // self._num_groups
205
+
206
+ x = idx % self._group_to_len[group_idx]
207
+ y = idx // self._group_to_len[group_idx]
208
+
209
+ file_paths_in_group = self._groups[group_idx].copy()
210
+
211
+ Random(y + 4617 * group_idx).shuffle(
212
+ file_paths_in_group
213
+ ) # todo: 4617 is arbitrary and could probably be zero.
214
+
215
+ file_path = file_paths_in_group[x]
216
+
217
+ return self.load_audio(file_path, record_key)
@@ -0,0 +1,35 @@
1
+ from functools import partial
2
+
3
+ from einops import rearrange
4
+ import jax
5
+ import jaxloudnorm as jln
6
+ from jax import numpy as jnp
7
+
8
+
9
+ @partial(jax.jit, static_argnames=("sample_rate", "zeros"))
10
+ def jit_integrated_loudness(data, sample_rate, zeros: int):
11
+
12
+ block_size = 0.4
13
+
14
+ original_length = data.shape[-1]
15
+ signal_duration = original_length / sample_rate
16
+
17
+ if signal_duration < block_size:
18
+ data = jnp.pad(
19
+ data,
20
+ pad_width=(
21
+ (0, 0),
22
+ (0, 0),
23
+ (0, int(block_size * sample_rate) - original_length),
24
+ ),
25
+ )
26
+
27
+ data = rearrange(data, "b c t -> b t c")
28
+ meter = jln.Meter(sample_rate, block_size=block_size, use_fir=True, zeros=zeros)
29
+ loudness = jax.vmap(meter.integrated_loudness)(data)
30
+
31
+ loudness = jnp.where(
32
+ jnp.isnan(loudness), jnp.full_like(loudness, -200), loudness
33
+ ) # todo: -200 dB good default?
34
+
35
+ return loudness