ableton-studio-mcp 1.17.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.
- ableton_studio_mcp-1.17.0/LICENSE +22 -0
- ableton_studio_mcp-1.17.0/MCP_Server/__init__.py +6 -0
- ableton_studio_mcp-1.17.0/MCP_Server/arrangement.py +274 -0
- ableton_studio_mcp-1.17.0/MCP_Server/audio_analysis.py +282 -0
- ableton_studio_mcp-1.17.0/MCP_Server/bundled_ableton_remote_script/AbletonMCP_init.py +4114 -0
- ableton_studio_mcp-1.17.0/MCP_Server/bundled_ableton_remote_script/__init__.py +0 -0
- ableton_studio_mcp-1.17.0/MCP_Server/device_knowledge.py +372 -0
- ableton_studio_mcp-1.17.0/MCP_Server/doctor.py +196 -0
- ableton_studio_mcp-1.17.0/MCP_Server/drums.py +415 -0
- ableton_studio_mcp-1.17.0/MCP_Server/midi_file.py +173 -0
- ableton_studio_mcp-1.17.0/MCP_Server/mix_analysis.py +616 -0
- ableton_studio_mcp-1.17.0/MCP_Server/music_styles.py +433 -0
- ableton_studio_mcp-1.17.0/MCP_Server/music_theory.py +1121 -0
- ableton_studio_mcp-1.17.0/MCP_Server/remote_script_install.py +333 -0
- ableton_studio_mcp-1.17.0/MCP_Server/script_handshake.py +161 -0
- ableton_studio_mcp-1.17.0/MCP_Server/server.py +3567 -0
- ableton_studio_mcp-1.17.0/PKG-INFO +365 -0
- ableton_studio_mcp-1.17.0/README.md +339 -0
- ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/PKG-INFO +365 -0
- ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/SOURCES.txt +40 -0
- ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/dependency_links.txt +1 -0
- ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/entry_points.txt +5 -0
- ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/requires.txt +2 -0
- ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/top_level.txt +1 -0
- ableton_studio_mcp-1.17.0/pyproject.toml +50 -0
- ableton_studio_mcp-1.17.0/setup.cfg +4 -0
- ableton_studio_mcp-1.17.0/tests/test_arrangement.py +142 -0
- ableton_studio_mcp-1.17.0/tests/test_arrangement_notes.py +276 -0
- ableton_studio_mcp-1.17.0/tests/test_async_live_state.py +402 -0
- ableton_studio_mcp-1.17.0/tests/test_clip_loop.py +211 -0
- ableton_studio_mcp-1.17.0/tests/test_clip_notes.py +186 -0
- ableton_studio_mcp-1.17.0/tests/test_devices.py +236 -0
- ableton_studio_mcp-1.17.0/tests/test_doctor.py +116 -0
- ableton_studio_mcp-1.17.0/tests/test_drums.py +247 -0
- ableton_studio_mcp-1.17.0/tests/test_error_reporting.py +94 -0
- ableton_studio_mcp-1.17.0/tests/test_handshake_retry.py +72 -0
- ableton_studio_mcp-1.17.0/tests/test_midi_audio_files.py +218 -0
- ableton_studio_mcp-1.17.0/tests/test_mix_analysis.py +144 -0
- ableton_studio_mcp-1.17.0/tests/test_music_theory.py +275 -0
- ableton_studio_mcp-1.17.0/tests/test_remote_script_bridge.py +236 -0
- ableton_studio_mcp-1.17.0/tests/test_routing_recording.py +617 -0
- ableton_studio_mcp-1.17.0/tests/test_warp_automation.py +496 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Olivier Cedrati
|
|
4
|
+
Copyright (c) 2025 Siddharth Ahuja (portions: the original ableton-mcp)
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
"""Long-form evolution and arrangement for electronic music.
|
|
2
|
+
|
|
3
|
+
* Automation curves over many bars (linear, exponential build, ease-out,
|
|
4
|
+
S-curve, slow sine/triangle LFO, phrase steps, random walk, swell) turned
|
|
5
|
+
into clip-envelope points.
|
|
6
|
+
* Clip extension: tile a short MIDI loop to 32/64 bars so a long envelope
|
|
7
|
+
can ride on it.
|
|
8
|
+
* Arrangement templates (DJ-friendly techno, compact 64-bar techno,
|
|
9
|
+
house, minimal) as sections with an energy level and the roles that play.
|
|
10
|
+
* Track roles from track names, and an arrangement plan: which Session clip
|
|
11
|
+
goes where in the Arrangement, tiled to fill each section, plus locators.
|
|
12
|
+
|
|
13
|
+
Live's API cannot write Arrangement automation, but a Session clip's
|
|
14
|
+
envelopes become track automation when the clip is copied to the
|
|
15
|
+
Arrangement (checked by ear in Live 12): automate a Session clip, then
|
|
16
|
+
place it with build_arrangement.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
import math
|
|
20
|
+
import random
|
|
21
|
+
from typing import Dict, List, Optional, Sequence
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class ArrangementError(ValueError):
|
|
25
|
+
pass
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
# ------------------------------------------------------------------ curves
|
|
29
|
+
|
|
30
|
+
def _shape(shape: str, t: float, cycles: float, steps: int, power: float, rnd: random.Random,
|
|
31
|
+
state: Dict) -> float:
|
|
32
|
+
"""0..1 for position t in 0..1."""
|
|
33
|
+
if shape == "linear":
|
|
34
|
+
return t
|
|
35
|
+
if shape in ("exp", "build", "ease_in"): # slow start, fast end: classic build-up
|
|
36
|
+
return t ** power
|
|
37
|
+
if shape in ("log", "ease_out", "release"):
|
|
38
|
+
return 1 - (1 - t) ** power
|
|
39
|
+
if shape in ("s_curve", "smooth"):
|
|
40
|
+
return t * t * (3 - 2 * t)
|
|
41
|
+
if shape == "swell": # up then back down
|
|
42
|
+
return math.sin(math.pi * t)
|
|
43
|
+
if shape == "sine":
|
|
44
|
+
return 0.5 - 0.5 * math.cos(2 * math.pi * cycles * t)
|
|
45
|
+
if shape == "triangle":
|
|
46
|
+
x = (cycles * t) % 1.0
|
|
47
|
+
return 2 * x if x < 0.5 else 2 * (1 - x)
|
|
48
|
+
if shape == "steps": # rises in equal stairs (e.g. one step per 8-bar phrase)
|
|
49
|
+
return min(math.floor(t * steps) / max(steps - 1, 1), 1.0)
|
|
50
|
+
if shape == "random_walk":
|
|
51
|
+
v = state.get("v", 0.5) + rnd.gauss(0, 0.06)
|
|
52
|
+
state["v"] = min(1.0, max(0.0, v))
|
|
53
|
+
return state["v"]
|
|
54
|
+
if shape == "hold":
|
|
55
|
+
return 0.0
|
|
56
|
+
raise ArrangementError("Unknown shape '%s'. Known: %s" % (shape, ", ".join(SHAPES)))
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
SHAPES = {
|
|
60
|
+
"linear": "Rampe régulière",
|
|
61
|
+
"exp": "Montée lente puis rapide (build-up classique ; power règle la courbure)",
|
|
62
|
+
"log": "Montée rapide puis douce (ouverture, release)",
|
|
63
|
+
"s_curve": "Départ et arrivée en douceur",
|
|
64
|
+
"swell": "Monte puis redescend (vague sur la durée)",
|
|
65
|
+
"sine": "LFO lent sinusoïdal (cycles = nombre d'allers-retours sur la durée)",
|
|
66
|
+
"triangle": "LFO lent triangulaire",
|
|
67
|
+
"steps": "Paliers (steps = nombre de paliers, ex. un par phrase de 8 mesures)",
|
|
68
|
+
"random_walk": "Dérive aléatoire douce (vie organique, seed)",
|
|
69
|
+
"hold": "Valeur fixe (start)",
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def curve_points(length_beats: float, start: float, end: float, shape: str = "linear",
|
|
74
|
+
resolution: float = 1.0, cycles: float = 1.0, steps: int = 4, power: float = 2.5,
|
|
75
|
+
offset: float = 0.0, seed: int = 0) -> List[Dict[str, float]]:
|
|
76
|
+
"""Envelope points {time, value} every ``resolution`` beats."""
|
|
77
|
+
if length_beats <= 0 or resolution <= 0:
|
|
78
|
+
raise ArrangementError("length and resolution must be positive")
|
|
79
|
+
rnd, state = random.Random(seed), {}
|
|
80
|
+
n = int(round(length_beats / resolution))
|
|
81
|
+
pts = []
|
|
82
|
+
for i in range(n + 1):
|
|
83
|
+
t = i / n if n else 1.0
|
|
84
|
+
y = _shape(shape, t, cycles, steps, power, rnd, state)
|
|
85
|
+
pts.append({"time": round(offset + i * resolution, 6), "value": round(start + (end - start) * y, 6)})
|
|
86
|
+
return pts
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def tile_notes(notes: List[Dict], loop_length: float, target_length: float) -> List[Dict]:
|
|
90
|
+
"""Repeat a loop's notes until target_length (beats)."""
|
|
91
|
+
if loop_length <= 0:
|
|
92
|
+
raise ArrangementError("loop length must be positive")
|
|
93
|
+
out, k = [], 0
|
|
94
|
+
while k * loop_length < target_length - 1e-9:
|
|
95
|
+
for n in notes:
|
|
96
|
+
s = n["start_time"] + k * loop_length
|
|
97
|
+
if s < target_length - 1e-9 and n["start_time"] < loop_length - 1e-9:
|
|
98
|
+
m = {key: n[key] for key in ("pitch", "start_time", "duration", "velocity", "mute") if key in n}
|
|
99
|
+
for opt in ("probability", "velocity_deviation", "release_velocity"):
|
|
100
|
+
if opt in n and n[opt] is not None:
|
|
101
|
+
m[opt] = n[opt]
|
|
102
|
+
m["start_time"] = round(s, 6)
|
|
103
|
+
m["duration"] = min(n["duration"], target_length - s)
|
|
104
|
+
out.append(m)
|
|
105
|
+
k += 1
|
|
106
|
+
return out
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
# ------------------------------------------------------------------- roles
|
|
110
|
+
|
|
111
|
+
ROLE_WORDS = [
|
|
112
|
+
("kick", ["kick", "kik", "bd", "grosse caisse"]),
|
|
113
|
+
("hats", ["hat", "hh", "hihat", "charley", "ride", "shaker", "top"]),
|
|
114
|
+
("perc", ["perc", "conga", "bongo", "tom", "rim", "clap", "snare", "cowbell", "clave"]),
|
|
115
|
+
("drums", ["drum", "beat", "batterie", "groove", "loop", "break"]),
|
|
116
|
+
("rumble", ["rumble"]),
|
|
117
|
+
("bass", ["bass", "basse", "sub", "303", "acid"]),
|
|
118
|
+
("chords", ["chord", "accord", "stab", "dub", "keys", "piano", "rhodes", "organ", "orgue"]),
|
|
119
|
+
("pad", ["pad", "nappe", "drone", "atmo", "ambience", "texture", "string"]),
|
|
120
|
+
("lead", ["lead", "synth", "arp", "melod", "hook", "seq"]),
|
|
121
|
+
("vocal", ["vocal", "vox", "voix", "voice", "chant"]),
|
|
122
|
+
("fx", ["fx", "riser", "sweep", "noise", "impact", "crash", "uplifter", "downlifter", "reverse"]),
|
|
123
|
+
]
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def infer_track_roles(tracks: List[Dict]) -> Dict[int, str]:
|
|
127
|
+
"""track index -> role from its name (first matching role wins)."""
|
|
128
|
+
roles = {}
|
|
129
|
+
for t in tracks:
|
|
130
|
+
name = " %s " % str(t.get("name", "")).lower().replace("_", " ").replace("-", " ")
|
|
131
|
+
for role, words in ROLE_WORDS:
|
|
132
|
+
if any(w in name for w in words):
|
|
133
|
+
roles[int(t["index"])] = role
|
|
134
|
+
break
|
|
135
|
+
return roles
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
# --------------------------------------------------------------- templates
|
|
139
|
+
|
|
140
|
+
def _sec(name, bars, energy, roles, tip=""):
|
|
141
|
+
return {"name": name, "bars": bars, "energy": energy, "roles": list(roles), "tip": tip}
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
ALL = ["kick", "drums", "hats", "perc", "rumble", "bass", "chords", "pad", "lead", "vocal", "fx"]
|
|
145
|
+
|
|
146
|
+
TEMPLATES: Dict[str, Dict] = {
|
|
147
|
+
"techno_dj": {
|
|
148
|
+
"label": "Techno, structure DJ (≈ 6-7 min à 130 BPM)",
|
|
149
|
+
"sections": [
|
|
150
|
+
_sec("Intro DJ", 32, 0.35, ["kick", "drums", "hats"],
|
|
151
|
+
"Kick + charleys seuls : le DJ cale sa transition. Varier les charleys tous les 8 mesures."),
|
|
152
|
+
_sec("Groove", 32, 0.6, ["kick", "drums", "hats", "perc", "rumble", "bass"],
|
|
153
|
+
"Entrée de la basse/rumble ; ouvrir lentement un filtre sur 32 mesures."),
|
|
154
|
+
_sec("Break 1", 16, 0.3, ["hats", "chords", "pad", "fx"],
|
|
155
|
+
"Kick coupé, l'harmonie respire ; réverbe et delay en hausse."),
|
|
156
|
+
_sec("Montée", 16, 0.75, ["drums", "hats", "perc", "chords", "fx"],
|
|
157
|
+
"Tension : filtre et résonance en courbe exp, roulement de clap, riser."),
|
|
158
|
+
_sec("Peak 1", 32, 1.0, ALL, "Tout entre ; garder un élément en réserve pour le peak 2."),
|
|
159
|
+
_sec("Break 2", 16, 0.4, ["perc", "chords", "pad", "lead", "fx"],
|
|
160
|
+
"Variation de l'accord ou du motif lead."),
|
|
161
|
+
_sec("Peak 2", 32, 1.0, ALL, "Version la plus intense (élément gardé en réserve, ouverture max)."),
|
|
162
|
+
_sec("Outro DJ", 32, 0.35, ["kick", "drums", "hats"],
|
|
163
|
+
"Retirer les éléments par 8 mesures, finir kick + charleys pour le mix."),
|
|
164
|
+
],
|
|
165
|
+
},
|
|
166
|
+
"techno_64": {
|
|
167
|
+
"label": "Techno compacte en 64 mesures (≈ 2 min à 130 BPM)",
|
|
168
|
+
"sections": [
|
|
169
|
+
_sec("Intro", 8, 0.35, ["kick", "drums", "hats"]),
|
|
170
|
+
_sec("Groove", 16, 0.65, ["kick", "drums", "hats", "perc", "rumble", "bass"]),
|
|
171
|
+
_sec("Break", 8, 0.3, ["hats", "chords", "pad", "fx"]),
|
|
172
|
+
_sec("Montée", 8, 0.75, ["drums", "hats", "perc", "chords", "fx"]),
|
|
173
|
+
_sec("Peak", 16, 1.0, ALL),
|
|
174
|
+
_sec("Outro", 8, 0.35, ["kick", "drums", "hats"]),
|
|
175
|
+
],
|
|
176
|
+
},
|
|
177
|
+
"minimal": {
|
|
178
|
+
"label": "Minimal / hypnotique (évolution par ajouts subtils)",
|
|
179
|
+
"sections": [
|
|
180
|
+
_sec("Intro", 16, 0.3, ["kick", "drums", "hats"]),
|
|
181
|
+
_sec("Couche 1", 16, 0.45, ["kick", "drums", "hats", "perc"]),
|
|
182
|
+
_sec("Couche 2", 16, 0.6, ["kick", "drums", "hats", "perc", "bass"]),
|
|
183
|
+
_sec("Couche 3", 32, 0.75, ["kick", "drums", "hats", "perc", "bass", "chords", "rumble"]),
|
|
184
|
+
_sec("Respiration", 8, 0.4, ["hats", "perc", "chords", "pad"]),
|
|
185
|
+
_sec("Plein", 32, 0.85, ALL),
|
|
186
|
+
_sec("Outro", 16, 0.3, ["kick", "drums", "hats"]),
|
|
187
|
+
],
|
|
188
|
+
},
|
|
189
|
+
"house": {
|
|
190
|
+
"label": "House (intro/outro 16 mesures, couplets-refrains)",
|
|
191
|
+
"sections": [
|
|
192
|
+
_sec("Intro", 16, 0.4, ["kick", "drums", "hats"]),
|
|
193
|
+
_sec("Groove", 16, 0.6, ["kick", "drums", "hats", "perc", "bass"]),
|
|
194
|
+
_sec("Partie A", 16, 0.75, ["kick", "drums", "hats", "perc", "bass", "chords"]),
|
|
195
|
+
_sec("Break", 16, 0.35, ["chords", "pad", "vocal", "fx"]),
|
|
196
|
+
_sec("Partie B", 32, 1.0, ALL),
|
|
197
|
+
_sec("Outro", 16, 0.4, ["kick", "drums", "hats"]),
|
|
198
|
+
],
|
|
199
|
+
},
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def template_sections(name: str) -> List[Dict]:
|
|
204
|
+
if name not in TEMPLATES:
|
|
205
|
+
raise ArrangementError("Unknown template '%s'. Known: %s" % (name, ", ".join(TEMPLATES)))
|
|
206
|
+
return [dict(s) for s in TEMPLATES[name]["sections"]]
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
# -------------------------------------------------------------------- plan
|
|
210
|
+
|
|
211
|
+
def plan_arrangement(sections: Sequence[Dict], tracks: List[Dict], track_roles: Dict[int, str],
|
|
212
|
+
beats_per_bar: float = 4.0, start_bar: int = 0, default_slot: int = 0) -> Dict:
|
|
213
|
+
"""Placements of Session clips in the Arrangement.
|
|
214
|
+
|
|
215
|
+
``tracks``: [{index, name, slots: {slot: length_beats}}].
|
|
216
|
+
Each section either lists ``roles`` (tracks whose role is in it play
|
|
217
|
+
their ``default_slot`` clip, or the section's ``slots`` override
|
|
218
|
+
{track_index: slot}) or gives ``play`` {track_index: slot or None}.
|
|
219
|
+
A clip is tiled to fill the section; a clip longer than the section is
|
|
220
|
+
placed once if it fits exactly, otherwise reported.
|
|
221
|
+
"""
|
|
222
|
+
by_index = {int(t["index"]): t for t in tracks}
|
|
223
|
+
placements, locators, warnings, table = [], [], [], []
|
|
224
|
+
bar = start_bar
|
|
225
|
+
for sec in sections:
|
|
226
|
+
bars = int(sec["bars"])
|
|
227
|
+
start = bar * beats_per_bar
|
|
228
|
+
end = start + bars * beats_per_bar
|
|
229
|
+
locators.append({"beat": start, "name": sec["name"]})
|
|
230
|
+
if "play" in sec and sec["play"] is not None:
|
|
231
|
+
plays = {int(k): v for k, v in sec["play"].items()}
|
|
232
|
+
else:
|
|
233
|
+
roles = set(sec.get("roles", []))
|
|
234
|
+
plays = {i: default_slot for i, r in track_roles.items() if r in roles}
|
|
235
|
+
for k, v in (sec.get("slots") or {}).items():
|
|
236
|
+
plays[int(k)] = v
|
|
237
|
+
playing = []
|
|
238
|
+
for ti, slot in sorted(plays.items()):
|
|
239
|
+
if slot is None:
|
|
240
|
+
continue
|
|
241
|
+
t = by_index.get(ti)
|
|
242
|
+
if t is None:
|
|
243
|
+
warnings.append("%s: track %d does not exist" % (sec["name"], ti))
|
|
244
|
+
continue
|
|
245
|
+
length = (t.get("slots") or {}).get(int(slot))
|
|
246
|
+
if not length:
|
|
247
|
+
warnings.append("%s: no clip in slot %d of '%s'" % (sec["name"], slot, t["name"]))
|
|
248
|
+
continue
|
|
249
|
+
pos = start
|
|
250
|
+
while pos + length <= end + 1e-6:
|
|
251
|
+
placements.append({"track_index": ti, "clip_index": int(slot), "start": pos})
|
|
252
|
+
pos += length
|
|
253
|
+
if pos < end - 1e-6:
|
|
254
|
+
warnings.append("%s: '%s' clip (%g beats) does not divide the section (%g beats); "
|
|
255
|
+
"%g beats left empty" % (sec["name"], t["name"], length, end - start, end - pos))
|
|
256
|
+
playing.append(t["name"])
|
|
257
|
+
table.append({"section": sec["name"], "bar": bar + 1, "bars": bars,
|
|
258
|
+
"energy": sec.get("energy"), "tracks": playing, "tip": sec.get("tip", "")})
|
|
259
|
+
bar += bars
|
|
260
|
+
return {"placements": placements, "locators": locators, "warnings": warnings, "sections": table,
|
|
261
|
+
"total_bars": bar - start_bar, "end_beat": bar * beats_per_bar}
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
def activity_map(clips_by_track: Dict[str, List[Dict]], block_beats: float, end_beat: float) -> Dict[str, str]:
|
|
265
|
+
"""One character per block: '#' if the track has a clip sounding there."""
|
|
266
|
+
blocks = int(math.ceil(end_beat / block_beats)) if end_beat > 0 else 0
|
|
267
|
+
out = {}
|
|
268
|
+
for name, clips in clips_by_track.items():
|
|
269
|
+
row = []
|
|
270
|
+
for b in range(blocks):
|
|
271
|
+
a, z = b * block_beats, (b + 1) * block_beats
|
|
272
|
+
row.append("#" if any(c["start_time"] < z and c["end_time"] > a for c in clips) else ".")
|
|
273
|
+
out[name] = "".join(row)
|
|
274
|
+
return out
|
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
"""Read a WAV/AIFF file and measure it (no dependency).
|
|
2
|
+
|
|
3
|
+
Gives the model a way to "listen" to a render or a recorded take: levels,
|
|
4
|
+
clipping, loudness over time, stereo width and a coarse spectral balance.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import math
|
|
8
|
+
import struct
|
|
9
|
+
from array import array
|
|
10
|
+
from typing import Dict, List, Tuple
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class AudioFileError(ValueError):
|
|
14
|
+
"""The file is not an audio file this reader handles."""
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
SILENCE_DB = -60.0
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _db(x: float) -> float:
|
|
21
|
+
return round(20 * math.log10(x), 2) if x > 1e-10 else -200.0
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _int24_to_array(raw: bytes, big_endian: bool) -> array:
|
|
25
|
+
"""24-bit PCM -> int32 array scaled by 256 (sign kept)."""
|
|
26
|
+
n = len(raw) // 3
|
|
27
|
+
out = bytearray(n * 4)
|
|
28
|
+
if big_endian:
|
|
29
|
+
out[0::4], out[1::4], out[2::4] = raw[0::3], raw[1::3], raw[2::3]
|
|
30
|
+
arr = array("i", bytes(out))
|
|
31
|
+
if arr.itemsize == 4 and struct.pack("=i", 1) != struct.pack(">i", 1):
|
|
32
|
+
arr.byteswap()
|
|
33
|
+
else:
|
|
34
|
+
out[1::4], out[2::4], out[3::4] = raw[0::3], raw[1::3], raw[2::3]
|
|
35
|
+
arr = array("i", bytes(out))
|
|
36
|
+
if struct.pack("=i", 1) != struct.pack("<i", 1):
|
|
37
|
+
arr.byteswap()
|
|
38
|
+
return arr
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _decode(raw: bytes, bits: int, is_float: bool, big_endian: bool) -> Tuple[array, float]:
|
|
42
|
+
"""Return (samples, full_scale)."""
|
|
43
|
+
native_big = struct.pack("=h", 1) == struct.pack(">h", 1)
|
|
44
|
+
swap = big_endian != native_big
|
|
45
|
+
if is_float:
|
|
46
|
+
code = {32: "f", 64: "d"}.get(bits)
|
|
47
|
+
if not code:
|
|
48
|
+
raise AudioFileError("Unsupported float width: %d bits" % bits)
|
|
49
|
+
arr = array(code, raw[: len(raw) - len(raw) % (bits // 8)])
|
|
50
|
+
if swap:
|
|
51
|
+
arr.byteswap()
|
|
52
|
+
return arr, 1.0
|
|
53
|
+
if bits == 8:
|
|
54
|
+
arr = array("b", bytes((b - 128) & 0xFF for b in raw)) if not big_endian else array("b", raw)
|
|
55
|
+
return arr, 128.0
|
|
56
|
+
if bits == 16:
|
|
57
|
+
arr = array("h", raw[: len(raw) - len(raw) % 2])
|
|
58
|
+
if swap:
|
|
59
|
+
arr.byteswap()
|
|
60
|
+
return arr, 32768.0
|
|
61
|
+
if bits == 24:
|
|
62
|
+
return _int24_to_array(raw[: len(raw) - len(raw) % 3], big_endian), float(2 ** 31)
|
|
63
|
+
if bits == 32:
|
|
64
|
+
arr = array("i", raw[: len(raw) - len(raw) % 4])
|
|
65
|
+
if swap:
|
|
66
|
+
arr.byteswap()
|
|
67
|
+
return arr, float(2 ** 31)
|
|
68
|
+
raise AudioFileError("Unsupported PCM width: %d bits" % bits)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _ieee_extended(b: bytes) -> float:
|
|
72
|
+
"""80-bit IEEE 754 extended (AIFF sample rate)."""
|
|
73
|
+
exp = ((b[0] & 0x7F) << 8) | b[1]
|
|
74
|
+
mant = struct.unpack(">Q", b[2:10])[0]
|
|
75
|
+
if exp == 0 and mant == 0:
|
|
76
|
+
return 0.0
|
|
77
|
+
return mant * 2.0 ** (exp - 16383 - 63)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def read_audio(path: str) -> Dict:
|
|
81
|
+
"""Return {"sample_rate", "channels", "bits", "samples" (interleaved), "full_scale"}."""
|
|
82
|
+
with open(path, "rb") as f:
|
|
83
|
+
data = f.read()
|
|
84
|
+
if data[:4] == b"RIFF" and data[8:12] == b"WAVE":
|
|
85
|
+
i, fmt, raw = 12, None, None
|
|
86
|
+
while i + 8 <= len(data):
|
|
87
|
+
cid, size = data[i:i + 4], struct.unpack("<I", data[i + 4:i + 8])[0]
|
|
88
|
+
body = data[i + 8:i + 8 + size]
|
|
89
|
+
if cid == b"fmt ":
|
|
90
|
+
tag, ch, sr, _, _, bits = struct.unpack("<HHIIHH", body[:16])
|
|
91
|
+
if tag == 0xFFFE and len(body) >= 26: # WAVE_FORMAT_EXTENSIBLE
|
|
92
|
+
tag = struct.unpack("<H", body[24:26])[0]
|
|
93
|
+
fmt = (tag, ch, sr, bits)
|
|
94
|
+
elif cid == b"data":
|
|
95
|
+
raw = body
|
|
96
|
+
i += 8 + size + (size & 1)
|
|
97
|
+
if not fmt or raw is None:
|
|
98
|
+
raise AudioFileError("WAV file without fmt or data chunk")
|
|
99
|
+
tag, ch, sr, bits = fmt
|
|
100
|
+
if tag not in (1, 3):
|
|
101
|
+
raise AudioFileError("Unsupported WAV encoding (format tag %d)" % tag)
|
|
102
|
+
samples, fs = _decode(raw, bits, tag == 3, big_endian=False)
|
|
103
|
+
return {"sample_rate": sr, "channels": ch, "bits": bits, "float": tag == 3,
|
|
104
|
+
"samples": samples, "full_scale": fs}
|
|
105
|
+
if data[:4] == b"FORM" and data[8:12] in (b"AIFF", b"AIFC"):
|
|
106
|
+
i, comm, raw, compression = 12, None, None, b"NONE"
|
|
107
|
+
while i + 8 <= len(data):
|
|
108
|
+
cid, size = data[i:i + 4], struct.unpack(">I", data[i + 4:i + 8])[0]
|
|
109
|
+
body = data[i + 8:i + 8 + size]
|
|
110
|
+
if cid == b"COMM":
|
|
111
|
+
ch, _, bits = struct.unpack(">hIh", body[:8])
|
|
112
|
+
sr = _ieee_extended(body[8:18])
|
|
113
|
+
if data[8:12] == b"AIFC" and len(body) >= 22:
|
|
114
|
+
compression = body[18:22]
|
|
115
|
+
comm = (ch, int(round(sr)), bits)
|
|
116
|
+
elif cid == b"SSND":
|
|
117
|
+
offset = struct.unpack(">I", body[:4])[0]
|
|
118
|
+
raw = body[8 + offset:]
|
|
119
|
+
i += 8 + size + (size & 1)
|
|
120
|
+
if not comm or raw is None:
|
|
121
|
+
raise AudioFileError("AIFF file without COMM or SSND chunk")
|
|
122
|
+
ch, sr, bits = comm
|
|
123
|
+
if compression in (b"NONE", b"twos"):
|
|
124
|
+
samples, fs = _decode(raw, bits, False, big_endian=True)
|
|
125
|
+
elif compression == b"sowt":
|
|
126
|
+
samples, fs = _decode(raw, bits, False, big_endian=False)
|
|
127
|
+
elif compression in (b"fl32", b"FL32"):
|
|
128
|
+
samples, fs = _decode(raw, 32, True, big_endian=True)
|
|
129
|
+
elif compression in (b"fl64", b"FL64"):
|
|
130
|
+
samples, fs = _decode(raw, 64, True, big_endian=True)
|
|
131
|
+
else:
|
|
132
|
+
raise AudioFileError("Unsupported AIFF-C compression %r" % compression)
|
|
133
|
+
return {"sample_rate": sr, "channels": ch, "bits": bits,
|
|
134
|
+
"float": compression.lower().startswith(b"fl"),
|
|
135
|
+
"samples": samples, "full_scale": fs}
|
|
136
|
+
raise AudioFileError("Not a WAV or AIFF file")
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _biquad(kind: str, cutoff: float, sr: float) -> Tuple[float, float, float, float, float]:
|
|
140
|
+
"""2nd-order Butterworth low/high-pass coefficients (RBJ cookbook),
|
|
141
|
+
normalised: (b0, b1, b2, a1, a2)."""
|
|
142
|
+
w0 = 2.0 * math.pi * min(cutoff, sr * 0.45) / sr
|
|
143
|
+
alpha = math.sin(w0) / (2.0 * math.sqrt(0.5))
|
|
144
|
+
cos_w0 = math.cos(w0)
|
|
145
|
+
if kind == "low":
|
|
146
|
+
b0 = b2 = (1.0 - cos_w0) / 2.0
|
|
147
|
+
b1 = 1.0 - cos_w0
|
|
148
|
+
else:
|
|
149
|
+
b0 = b2 = (1.0 + cos_w0) / 2.0
|
|
150
|
+
b1 = -(1.0 + cos_w0)
|
|
151
|
+
a0 = 1.0 + alpha
|
|
152
|
+
return b0 / a0, b1 / a0, b2 / a0, (-2.0 * cos_w0) / a0, (1.0 - alpha) / a0
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _band_energy(x: List[float], coeffs) -> float:
|
|
156
|
+
b0, b1, b2, a1, a2 = coeffs
|
|
157
|
+
x1 = x2 = y1 = y2 = 0.0
|
|
158
|
+
energy = 0.0
|
|
159
|
+
for v in x:
|
|
160
|
+
y = b0 * v + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2
|
|
161
|
+
x2, x1, y2, y1 = x1, v, y1, y
|
|
162
|
+
energy += y * y
|
|
163
|
+
return energy
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def analyze_audio(path: str, segment_seconds: float = 1.0, max_segments: int = 240) -> Dict:
|
|
167
|
+
"""Levels, clipping, loudness over time, stereo and spectral balance."""
|
|
168
|
+
info = read_audio(path)
|
|
169
|
+
sr, ch, fs = info["sample_rate"], max(info["channels"], 1), info["full_scale"]
|
|
170
|
+
s = info["samples"]
|
|
171
|
+
frames = len(s) // ch
|
|
172
|
+
if frames == 0:
|
|
173
|
+
raise AudioFileError("The file has no audio frames")
|
|
174
|
+
duration = frames / float(sr)
|
|
175
|
+
scale = 1.0 / fs
|
|
176
|
+
|
|
177
|
+
chans = [s[c::ch] for c in range(ch)]
|
|
178
|
+
per_channel = []
|
|
179
|
+
clip_level = 0.999 * fs
|
|
180
|
+
for c, x in enumerate(chans):
|
|
181
|
+
peak = max(max(x), -min(x)) * scale
|
|
182
|
+
sumsq = math.fsum(v * v for v in x) * scale * scale
|
|
183
|
+
clipped = sum(1 for v in x if v >= clip_level or v <= -clip_level)
|
|
184
|
+
per_channel.append({
|
|
185
|
+
"channel": c,
|
|
186
|
+
"peak_dbfs": _db(peak),
|
|
187
|
+
"rms_dbfs": _db(math.sqrt(sumsq / len(x))),
|
|
188
|
+
"clipped_samples": clipped,
|
|
189
|
+
"dc_offset": round(sum(x) * scale / len(x), 6),
|
|
190
|
+
})
|
|
191
|
+
|
|
192
|
+
# Mono mix, used for time and spectral analysis.
|
|
193
|
+
if ch == 1:
|
|
194
|
+
mono = [v * scale for v in chans[0]]
|
|
195
|
+
else:
|
|
196
|
+
mono = [sum(fr) * scale / ch for fr in zip(*chans)]
|
|
197
|
+
|
|
198
|
+
peak = max(pc["peak_dbfs"] for pc in per_channel)
|
|
199
|
+
total_rms = _db(math.sqrt(math.fsum(v * v for v in mono) / frames))
|
|
200
|
+
|
|
201
|
+
# Loudness over time (RMS per segment of the mono mix).
|
|
202
|
+
seg = max(int(sr * segment_seconds), 1)
|
|
203
|
+
nseg = int(math.ceil(frames / float(seg)))
|
|
204
|
+
if nseg > max_segments:
|
|
205
|
+
seg = int(math.ceil(frames / float(max_segments)))
|
|
206
|
+
nseg = int(math.ceil(frames / float(seg)))
|
|
207
|
+
segments: List[Dict] = []
|
|
208
|
+
for k in range(nseg):
|
|
209
|
+
part = mono[k * seg:(k + 1) * seg]
|
|
210
|
+
if not part:
|
|
211
|
+
break
|
|
212
|
+
rms = math.sqrt(math.fsum(v * v for v in part) / len(part))
|
|
213
|
+
segments.append({
|
|
214
|
+
"t": round(k * seg / float(sr), 2),
|
|
215
|
+
"rms_dbfs": _db(rms),
|
|
216
|
+
"peak_dbfs": _db(max(max(part), -min(part))),
|
|
217
|
+
})
|
|
218
|
+
|
|
219
|
+
# Leading / trailing silence.
|
|
220
|
+
thr = 10 ** (SILENCE_DB / 20)
|
|
221
|
+
first = next((i for i, v in enumerate(mono) if abs(v) > thr), None)
|
|
222
|
+
last = next((i for i in range(frames - 1, -1, -1) if abs(mono[i]) > thr), None)
|
|
223
|
+
|
|
224
|
+
# Coarse spectral balance with 2nd-order Butterworth filters:
|
|
225
|
+
# low < 250 Hz, high > 4 kHz, mid = the rest of the energy.
|
|
226
|
+
e_all = math.fsum(v * v for v in mono)
|
|
227
|
+
e_lo = _band_energy(mono, _biquad("low", 250.0, sr))
|
|
228
|
+
e_hi = _band_energy(mono, _biquad("high", 4000.0, sr))
|
|
229
|
+
e_mid = max(e_all - e_lo - e_hi, 0.0)
|
|
230
|
+
bands = {}
|
|
231
|
+
if e_all > 0:
|
|
232
|
+
bands = {
|
|
233
|
+
"low_below_250hz_pct": round(100 * e_lo / e_all, 1),
|
|
234
|
+
"mid_pct": round(100 * e_mid / e_all, 1),
|
|
235
|
+
"high_above_4khz_pct": round(100 * e_hi / e_all, 1),
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
stereo = None
|
|
239
|
+
if ch >= 2:
|
|
240
|
+
l, r = chans[0], chans[1]
|
|
241
|
+
sll = math.fsum(v * v for v in l)
|
|
242
|
+
srr = math.fsum(v * v for v in r)
|
|
243
|
+
slr = math.fsum(a * b for a, b in zip(l, r))
|
|
244
|
+
corr = slr / math.sqrt(sll * srr) if sll > 0 and srr > 0 else None
|
|
245
|
+
stereo = {
|
|
246
|
+
"correlation": round(corr, 3) if corr is not None else None,
|
|
247
|
+
"balance_db_left_minus_right": round(
|
|
248
|
+
per_channel[0]["rms_dbfs"] - per_channel[1]["rms_dbfs"], 2),
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
loud = [sg for sg in segments if sg["rms_dbfs"] > SILENCE_DB]
|
|
252
|
+
loudest = max(loud, key=lambda sg: sg["rms_dbfs"]) if loud else None
|
|
253
|
+
warnings = []
|
|
254
|
+
if any(pc["clipped_samples"] for pc in per_channel) or peak >= -0.1:
|
|
255
|
+
warnings.append("clipping: peak at or near 0 dBFS")
|
|
256
|
+
if peak < -18:
|
|
257
|
+
warnings.append("quiet: peak below -18 dBFS")
|
|
258
|
+
if stereo and stereo["correlation"] is not None and stereo["correlation"] < 0:
|
|
259
|
+
warnings.append("phase: negative stereo correlation (mono-incompatible)")
|
|
260
|
+
if first is None:
|
|
261
|
+
warnings.append("silent: nothing above %d dBFS" % SILENCE_DB)
|
|
262
|
+
|
|
263
|
+
return {
|
|
264
|
+
"file": path,
|
|
265
|
+
"sample_rate": sr,
|
|
266
|
+
"channels": ch,
|
|
267
|
+
"bits": info["bits"],
|
|
268
|
+
"float": info["float"],
|
|
269
|
+
"duration_s": round(duration, 3),
|
|
270
|
+
"peak_dbfs": peak,
|
|
271
|
+
"rms_dbfs": total_rms,
|
|
272
|
+
"crest_factor_db": round(peak - total_rms, 2) if total_rms > -200 else None,
|
|
273
|
+
"per_channel": per_channel,
|
|
274
|
+
"stereo": stereo,
|
|
275
|
+
"spectral_balance": bands,
|
|
276
|
+
"leading_silence_s": round(first / float(sr), 3) if first is not None else None,
|
|
277
|
+
"trailing_silence_s": round((frames - 1 - last) / float(sr), 3) if last is not None else None,
|
|
278
|
+
"loudest_segment": loudest,
|
|
279
|
+
"segment_seconds": round(seg / float(sr), 3),
|
|
280
|
+
"segments": segments,
|
|
281
|
+
"warnings": warnings,
|
|
282
|
+
}
|