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.
Files changed (42) hide show
  1. ableton_studio_mcp-1.17.0/LICENSE +22 -0
  2. ableton_studio_mcp-1.17.0/MCP_Server/__init__.py +6 -0
  3. ableton_studio_mcp-1.17.0/MCP_Server/arrangement.py +274 -0
  4. ableton_studio_mcp-1.17.0/MCP_Server/audio_analysis.py +282 -0
  5. ableton_studio_mcp-1.17.0/MCP_Server/bundled_ableton_remote_script/AbletonMCP_init.py +4114 -0
  6. ableton_studio_mcp-1.17.0/MCP_Server/bundled_ableton_remote_script/__init__.py +0 -0
  7. ableton_studio_mcp-1.17.0/MCP_Server/device_knowledge.py +372 -0
  8. ableton_studio_mcp-1.17.0/MCP_Server/doctor.py +196 -0
  9. ableton_studio_mcp-1.17.0/MCP_Server/drums.py +415 -0
  10. ableton_studio_mcp-1.17.0/MCP_Server/midi_file.py +173 -0
  11. ableton_studio_mcp-1.17.0/MCP_Server/mix_analysis.py +616 -0
  12. ableton_studio_mcp-1.17.0/MCP_Server/music_styles.py +433 -0
  13. ableton_studio_mcp-1.17.0/MCP_Server/music_theory.py +1121 -0
  14. ableton_studio_mcp-1.17.0/MCP_Server/remote_script_install.py +333 -0
  15. ableton_studio_mcp-1.17.0/MCP_Server/script_handshake.py +161 -0
  16. ableton_studio_mcp-1.17.0/MCP_Server/server.py +3567 -0
  17. ableton_studio_mcp-1.17.0/PKG-INFO +365 -0
  18. ableton_studio_mcp-1.17.0/README.md +339 -0
  19. ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/PKG-INFO +365 -0
  20. ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/SOURCES.txt +40 -0
  21. ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/dependency_links.txt +1 -0
  22. ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/entry_points.txt +5 -0
  23. ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/requires.txt +2 -0
  24. ableton_studio_mcp-1.17.0/ableton_studio_mcp.egg-info/top_level.txt +1 -0
  25. ableton_studio_mcp-1.17.0/pyproject.toml +50 -0
  26. ableton_studio_mcp-1.17.0/setup.cfg +4 -0
  27. ableton_studio_mcp-1.17.0/tests/test_arrangement.py +142 -0
  28. ableton_studio_mcp-1.17.0/tests/test_arrangement_notes.py +276 -0
  29. ableton_studio_mcp-1.17.0/tests/test_async_live_state.py +402 -0
  30. ableton_studio_mcp-1.17.0/tests/test_clip_loop.py +211 -0
  31. ableton_studio_mcp-1.17.0/tests/test_clip_notes.py +186 -0
  32. ableton_studio_mcp-1.17.0/tests/test_devices.py +236 -0
  33. ableton_studio_mcp-1.17.0/tests/test_doctor.py +116 -0
  34. ableton_studio_mcp-1.17.0/tests/test_drums.py +247 -0
  35. ableton_studio_mcp-1.17.0/tests/test_error_reporting.py +94 -0
  36. ableton_studio_mcp-1.17.0/tests/test_handshake_retry.py +72 -0
  37. ableton_studio_mcp-1.17.0/tests/test_midi_audio_files.py +218 -0
  38. ableton_studio_mcp-1.17.0/tests/test_mix_analysis.py +144 -0
  39. ableton_studio_mcp-1.17.0/tests/test_music_theory.py +275 -0
  40. ableton_studio_mcp-1.17.0/tests/test_remote_script_bridge.py +236 -0
  41. ableton_studio_mcp-1.17.0/tests/test_routing_recording.py +617 -0
  42. 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,6 @@
1
+ """Ableton Live integration through the Model Context Protocol."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ # Expose key classes and functions for easier imports
6
+ from .server import AbletonConnection, get_ableton_connection
@@ -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
+ }