Source code for acoustic_spaces.spatial.loudspeakers

"""Loudspeaker layouts and vector base amplitude panning (VBAP, Pulkki 1997).

Each arrival is panned between the pair (horizontal layouts) or triangle (layouts with
height) of loudspeakers around its direction, with gains of unit total power. Layouts
with height but nothing below the listener get an imaginary loudspeaker straight down
(and one straight up when nothing is high). Its share is dropped, so arrivals from below
play from the speakers at their azimuth; straight down, all its neighbours play alike.
A gap wider than 90 degrees between the speakers on the horizon (behind the listener in
5.x.4) gets imaginary speakers on the horizon too, which hand their share to the two
speakers either side, so arrivals there stay on the horizon instead of going up to the
height layer. Four or more speakers on one plane (the height ring of the .4 layouts, the
rear corners of 7.x.4) get an imaginary speaker at their middle, which they play alike,
so a symmetric layout pans symmetrically and straight up plays from all four.
Low-frequency effects channels (LFE) take no part in panning and stay silent: a room's
bass reaches every speaker already, and bass management belongs to the playback system.
"""

from __future__ import annotations

import itertools
import math
from dataclasses import dataclass, field

import numpy as np

from acoustic_spaces.spatial.directions import from_angles


[docs] @dataclass(frozen=True) class Speaker: name: str azimuth: float # degrees, positive to the left elevation: float = 0.0 # degrees, positive up lfe: bool = False # a low-frequency effects channel: silent
def _layout(*speakers: tuple[str, float, float]) -> tuple[Speaker, ...]: return tuple(Speaker(*s) for s in speakers) def _with_lfe(speakers: tuple[Speaker, ...]) -> tuple[Speaker, ...]: """The layout with an LFE channel after the centre, as in WAV channel order.""" return (*speakers[:3], Speaker("LFE", 0.0, 0.0, lfe=True), *speakers[3:]) #: Named layouts after ITU-R BS.2051, in the channel order of multichannel WAV files. LAYOUTS: dict[str, tuple[Speaker, ...]] = { "stereo": _layout(("L", 30, 0), ("R", -30, 0)), "5.0": _layout(("L", 30, 0), ("R", -30, 0), ("C", 0, 0), ("Ls", 110, 0), ("Rs", -110, 0)), "7.0": _layout( ("L", 30, 0), ("R", -30, 0), ("C", 0, 0), ("Lrs", 135, 0), ("Rrs", -135, 0), ("Lss", 90, 0), ("Rss", -90, 0), ), "5.0.4": _layout( ("L", 30, 0), ("R", -30, 0), ("C", 0, 0), ("Ls", 110, 0), ("Rs", -110, 0), ("Ltf", 45, 30), ("Rtf", -45, 30), ("Ltb", 135, 30), ("Rtb", -135, 30), ), "7.0.4": _layout( ("L", 30, 0), ("R", -30, 0), ("C", 0, 0), ("Lrs", 135, 0), ("Rrs", -135, 0), ("Lss", 90, 0), ("Rss", -90, 0), ("Ltf", 45, 30), ("Rtf", -45, 30), ("Ltb", 135, 30), ("Rtb", -135, 30), ), } LAYOUTS.update({f"{name[0]}.1{name[3:]}": _with_lfe(LAYOUTS[name]) for name in list(LAYOUTS)[1:]}) #: WAVE_FORMAT_EXTENSIBLE speaker positions, for the channel mask of named layouts. _WAV_POSITIONS = { "L": 0x1, "R": 0x2, "C": 0x4, "LFE": 0x8, "Lrs": 0x10, "Rrs": 0x20, "Ls": 0x200, "Rs": 0x400, "Lss": 0x200, "Rss": 0x400, "Ltf": 0x1000, "Rtf": 0x4000, "Ltb": 0x8000, "Rtb": 0x20000, } # 5.0 files put the surrounds in the back positions. _WAV_POSITIONS_5 = {**_WAV_POSITIONS, "Ls": 0x10, "Rs": 0x20} _EPS = 1e-9 #: Speakers this close to the horizon (degrees) count as on it, and a gap between them #: wider than ``_MAX_GAP_DEG`` gets imaginary speakers on the horizon. _HORIZON_DEG = 10.0 _MAX_GAP_DEG = 90.0 #: Twice the area of a triangle of points on the unit sphere below which rounding #: leaves the direction of its plane loose. Such a triangle has two corners within #: ``_CLOSE`` of each other: twice the area is at least the product of its sides over 2, #: as its circle on the sphere has a radius of 1 at most. _THIN = 1e-5 _CLOSE = 1.1 * (2.0 * _THIN) ** (1.0 / 3.0) def _triples_to_try(points: np.ndarray, reach: float) -> list[tuple[int, int, int]] | None: """The triples of ``points`` (on or near the unit sphere) in increasing order among which a search over every triple for faces of their convex hull finds all it does, when it holds a triple's points to less than ``reach`` from its plane (well within it) for any triple whose cross product reaches ``_THIN``. A plane with every point on one side, as near as that, touches the hull at a corner and holds only the points within ``reach`` of the plane of one of the hull's triangles at that corner (Qhull's), as the others lie further below it: so the triples of the corner's star, it and those points. Thinner triples have two points within ``_CLOSE``, and every triple with two such is tried. None, for every triple to be tried, where the points are not 64-bit floats (whose rounding that takes), where Qhull cannot take them (fewer than four, all on one plane, or not finite), or where it leaves one off the hull or makes a triangle as thin. """ from scipy.spatial import ConvexHull, QhullError if not isinstance(points, np.ndarray) or points.dtype != np.float64: return None if points.shape[1:] != (3,) or len(points) < 4 or not np.isfinite(points).all(): return None try: hull = ConvexHull(points) except QhullError: return None if len(hull.vertices) < len(points): return None faces = hull.simplices a, b, c = (points[faces[:, m]] for m in range(3)) normal = np.cross(b - a, c - a) length = np.linalg.norm(normal, axis=1) if length.min() < _THIN: return None normal /= length[:, None] near = np.abs(points @ normal.T - np.einsum("fk,fk->f", normal, a)) < reach triples = set() for corner in range(len(points)): star = np.flatnonzero(near[:, np.any(faces == corner, axis=1)].any(axis=1)) triples.update(itertools.combinations(star.tolist(), 3)) gaps = np.linalg.norm(points[:, None, :] - points[None, :, :], axis=2) for i, j in zip(*np.nonzero(np.triu(gaps < _CLOSE, 1)), strict=True): for k in range(len(points)): if k != i and k != j: triples.add(tuple(sorted((int(i), int(j), k)))) return sorted(triples) def _flat_faces(points: np.ndarray, exhaustive: bool = False) -> list[tuple[int, ...]]: """The points on each face of the convex hull of ``points`` that holds four or more. A face's points are those within 1e-9 of the plane of a triple of them with every point on one side of it. The triples tried are those of :func:`_triples_to_try` (rounding moves the direction of a plane by up to about 1e-14 over its cross product, so up to 1e-9 at ``_THIN``), unless ``exhaustive``: then every triple is. """ triples = None if exhaustive else _triples_to_try(points, 2e-8) if triples is None: triples = itertools.combinations(range(len(points)), 3) faces = set() for i, j, k in triples: normal = np.cross(points[j] - points[i], points[k] - points[i]) if np.linalg.norm(normal) < 1e-12: continue side = (points - points[i]) @ (normal / np.linalg.norm(normal)) on = np.abs(side) < 1e-9 if on.sum() > 3 and (np.all(side < 1e-9) or np.all(side > -1e-9)): faces.add(tuple(np.flatnonzero(on))) return sorted(faces) def _hull_triangles(points: np.ndarray, exhaustive: bool = False) -> list[tuple[int, int, int]]: """Faces of the convex hull of points on the unit sphere around the origin. Points are nudged a tiny, fixed amount first, so four on one plane give two triangles rather than four overlapping ones. A face is a triple of points with every other point on one side of its plane, to 1e-12 times its cross product (so to 1e-7 at ``_THIN``). The triples tried are those of :func:`_triples_to_try`, unless ``exhaustive``: then every triple is. """ nudged = points + 1e-7 * np.random.default_rng(0).standard_normal(points.shape) triples = None if exhaustive else _triples_to_try(nudged, 3e-7) if triples is None: triples = itertools.combinations(range(len(points)), 3) faces = [] for i, j, k in triples: normal = np.cross(nudged[j] - nudged[i], nudged[k] - nudged[i]) if np.linalg.norm(normal) < 1e-12: continue side = (nudged - nudged[i]) @ normal side[[i, j, k]] = 0.0 if np.all(side <= 1e-12) or np.all(side >= -1e-12): faces.append((i, j, k)) return faces
[docs] @dataclass(frozen=True) class Loudspeakers: """A loudspeaker layout: a name from :data:`LAYOUTS` or a list of speakers.""" speakers: tuple[Speaker, ...] name: str = "speakers" _bases: list = field(init=False, repr=False, compare=False) _downmix: np.ndarray = field(init=False, repr=False, compare=False) @classmethod def layout(cls, name: str) -> Loudspeakers: if name not in LAYOUTS: raise ValueError(f"unknown layout {name!r}; use one of {', '.join(LAYOUTS)}") return cls(LAYOUTS[name], name) def __post_init__(self) -> None: if len(self.speakers) < 2: raise ValueError("a loudspeaker layout needs at least two speakers") names = [s.name for s in self.speakers] if len(set(names)) != len(names): raise ValueError("loudspeaker names must be unique") if sum(not s.lfe for s in self.speakers) < 2: raise ValueError("a loudspeaker layout needs at least two speakers besides LFE") object.__setattr__(self, "speakers", tuple(self.speakers)) bases, downmix = self._make_bases() object.__setattr__(self, "_bases", bases) object.__setattr__(self, "_downmix", downmix) @property def channels(self) -> int: return len(self.speakers) @property def label(self) -> str: return self.name
[docs] def pressure_gains(self) -> np.ndarray: """(channels,) what each channel picks up of a sound pressure that is the same all over the room: 1/√n in each of the n main speakers, at unit power as the panning plays one direction (on a layout without height speakers, as it plays sound from straight above or below), and none in the LFE.""" mains = [not s.lfe for s in self.speakers] return np.where(mains, 1.0 / math.sqrt(sum(mains)), 0.0)
@property def channel_names(self) -> list[str]: return [s.name for s in self.speakers] @property def horizontal(self) -> bool: return all(abs(s.elevation) < 1e-6 for s in self._mains()) def _mains(self) -> list[Speaker]: return [s for s in self.speakers if not s.lfe]
[docs] def channel_mask(self) -> int: """WAV channel mask of a named layout; 0 (no assignment) for others.""" if self.name not in LAYOUTS: return 0 positions = _WAV_POSITIONS_5 if self.name.startswith("5.") else _WAV_POSITIONS mask = 0 for s in self.speakers: mask |= positions[s.name] return mask
def directions(self) -> np.ndarray: return from_angles([s.azimuth for s in self.speakers], [s.elevation for s in self.speakers]) def _make_bases(self): """Pairs or triangles of the speakers other than LFE, by their index among them (imaginary speakers after the real ones), and the gains (points, mains) with which each of them plays through the real speakers.""" mains = self._mains() n_real = len(mains) real = from_angles([s.azimuth for s in mains], [s.elevation for s in mains]) if self.horizontal: order = np.argsort([s.azimuth % 360.0 for s in mains]) pairs = [] for a, b in zip(order, np.roll(order, -1), strict=True): span = (mains[b].azimuth - mains[a].azimuth) % 360.0 if 0.0 < span < 180.0 - 1e-6: pairs.append((np.linalg.inv(real[[a, b], :2].T), (a, b))) return pairs, np.eye(n_real) elevations = np.array([s.elevation for s in mains]) extra, downmix = [], [] # Wide gaps on the horizon: imaginary speakers spread evenly across each, played # by the speakers either side with the pair's own VBAP gains, so that panning on # the horizon is the pair's; across 180 degrees or more, with constant power. horizon = sorted( (i for i, s in enumerate(mains) if abs(s.elevation) < _HORIZON_DEG), key=lambda i: mains[i].azimuth % 360.0, ) if len(horizon) >= 2: for a, b in zip(horizon, horizon[1:] + horizon[:1], strict=True): gap = (mains[b].azimuth - mains[a].azimuth) % 360.0 count = math.ceil(gap / _MAX_GAP_DEG - 1e-9) - 1 for k in range(1, count + 1): t = k / (count + 1) point = from_angles(mains[a].azimuth + t * gap, 0.0) row = np.zeros(n_real) if gap < 180.0 - 1e-6: pair = np.column_stack([real[a, :2], real[b, :2]]) row[a], row[b] = np.linalg.solve(pair, point[:2]) else: row[a], row[b] = math.cos(t * math.pi / 2), math.sin(t * math.pi / 2) extra.append(point) downmix.append(row) # Nothing below (or above): an imaginary speaker at the pole, whose share is dropped. if elevations.min() > -_HORIZON_DEG: extra.append([0.0, 0.0, -1.0]) downmix.append(np.zeros(n_real)) if elevations.max() < _HORIZON_DEG: extra.append([0.0, 0.0, 1.0]) downmix.append(np.zeros(n_real)) points = np.vstack([real, np.array(extra).reshape(-1, 3)]) downmix = np.vstack([np.eye(n_real), np.array(downmix).reshape(-1, n_real)]) # Four or more on one face of the hull: an imaginary speaker at their middle that # they play alike (adding up to its direction), so that the face is split evenly # around it rather than along one diagonal. for face in _flat_faces(points): middle = points[list(face)].sum(axis=0) length = np.linalg.norm(middle) points = np.vstack([points, middle / length]) downmix = np.vstack([downmix, downmix[list(face)].sum(axis=0) / length]) bases = [] for face in _hull_triangles(points): matrix = points[list(face)].T if abs(np.linalg.det(matrix)) > 1e-9: bases.append((np.linalg.inv(matrix), face)) return bases, downmix
[docs] def gains(self, directions: np.ndarray) -> np.ndarray: """VBAP gains (dirs, channels) of unit power for head directions (dirs, 3).""" v = np.atleast_2d(np.asarray(directions, dtype=float)) mains = self._mains() n_real = len(mains) main_directions = from_angles([s.azimuth for s in mains], [s.elevation for s in mains]) out = np.zeros((len(v), n_real)) horizontal = self.horizontal for row, p in enumerate(v): if horizontal: p = p[:2] if np.linalg.norm(p) < _EPS: # straight up or down: all speakers alike out[row] = 1.0 / math.sqrt(n_real) continue best, best_g, best_idx = -math.inf, None, None for inverse, idx in self._bases: g = inverse @ p if g.min() > best: best, best_g, best_idx = g.min(), g, idx if best_g is None or best < -1e-6: # Outside every pair (behind a stereo pair): the nearest speaker. out[row, int(np.argmax(main_directions[:, : len(p)] @ p))] = 1.0 else: # On an edge or a corner of the triangle, rounding leaves the speakers away # from it gains of about 1e-17, positive with some processors' arithmetic and # not with others'; they play nothing, so all give the same gains. g = np.where(best_g > 1e-12, best_g, 0.0) out[row] = g @ self._downmix[list(best_idx)] if np.linalg.norm(out[row]) < 1e-6: # at an imaginary speaker at a pole pole = best_idx[int(np.argmax(g))] for _, face in self._bases: if pole in face: others = [j for j in face if j != pole] out[row] = np.maximum(out[row], (self._downmix[others] > 0).any(axis=0)) out[row] /= np.linalg.norm(out[row]) full = np.zeros((len(v), self.channels)) full[:, [i for i, s in enumerate(self.speakers) if not s.lfe]] = out return full
__all__ = ["LAYOUTS", "Loudspeakers", "Speaker"]