pyFDN 0.1.0__tar.gz → 0.2.0__tar.gz

pyfdn-0.2.0/HISTORY.rst

@@ -0,0 +1,17 @@
+=======
+History
+=======
+
+0.2.0 (2026-08-10)
+------------------
+
+* Package compact audio examples and predefined colorless-FDN coefficients so
+  browser-hosted tutorials work without repository-relative files.
+* Add public APIs for packaged audio, FDN presets, and paper references.
+* Add generated documentation galleries and wheel-content checks.
+* Keep decay-estimation dependencies optional for a smaller core installation.
+
+0.1.0 (2025-07-02)
+------------------
+
+* First release on PyPI.

{pyfdn-0.1.0 → pyfdn-0.2.0}/MANIFEST.in

@@ -8,4 +8,4 @@ recursive-include tests *
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
 
-recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif
+recursive-include docs *.rst *.py Makefile make.bat *.jpg *.png *.gif

{pyfdn-0.1.0 → pyfdn-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyFDN
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python library for Feedback Delay Networks
 Author: Sebastian J. Schlecht, Facundo Franchino, Jeremy Bai
 Maintainer: Facundo Franchino, Sebastian J. Schlecht
@@ -16,20 +16,23 @@ Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
+License-File: src/pyFDN/resources/ATTRIBUTION.md
+License-File: src/pyFDN/resources/licenses/diff-fdn-colorless-MIT.txt
 Requires-Dist: numpy
 Requires-Dist: soundfile
 Requires-Dist: scipy
 Requires-Dist: flamo>=0.2.14
 Requires-Dist: flareverb
-Requires-Dist: pyroomacoustics
 Provides-Extra: examples
 Requires-Dist: marimo; extra == "examples"
 Requires-Dist: matplotlib>=3.5.0; extra == "examples"
 Requires-Dist: plotly>=5.0.0; extra == "examples"
+Requires-Dist: multislope>=0.1.1; extra == "examples"
 Provides-Extra: test
 Requires-Dist: marimo; extra == "test"
 Requires-Dist: matplotlib>=3.5.0; extra == "test"
 Requires-Dist: plotly>=5.0.0; extra == "test"
+Requires-Dist: multislope>=0.1.1; extra == "test"
 Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-cov>=4.0.0; extra == "test"
 Requires-Dist: coverage>=7.0.0; extra == "test"
@@ -56,6 +59,7 @@ Requires-Dist: ipykernel>=6.0.0; extra == "docs"
 Requires-Dist: pandoc>=2.0; extra == "docs"
 Requires-Dist: plotly>=5.0.0; extra == "docs"
 Requires-Dist: matplotlib>=3.5.0; extra == "docs"
+Requires-Dist: multislope>=0.1.1; extra == "docs"
 Dynamic: license-file
 
 =====
@@ -89,6 +93,11 @@ Overview
 
 ``pyFDN`` provides building blocks for designing, simulating, and analysing Feedback Delay Networks (FDNs). The package focuses on reusable, tested helper functions that simplify typical FDN workflows such as creating orthogonal feedback matrices, designing loop filters, and inspecting pole locations. Using ``flamo`` as a dependency, ``pyFDN`` allows modular design of advanced FDN structure with DSP operations in time and frequency domain.
 
+The source code is MIT-licensed. Small packaged tutorial resources retain the
+separate terms recorded in ``src/pyFDN/resources/ATTRIBUTION.md``; in
+particular, the Pori concert-hall impulse response is limited to
+noncommercial use.
+
 
 Highlights
 ----------

{pyfdn-0.1.0 → pyfdn-0.2.0}/README.rst

@@ -29,6 +29,11 @@ Overview
 
 ``pyFDN`` provides building blocks for designing, simulating, and analysing Feedback Delay Networks (FDNs). The package focuses on reusable, tested helper functions that simplify typical FDN workflows such as creating orthogonal feedback matrices, designing loop filters, and inspecting pole locations. Using ``flamo`` as a dependency, ``pyFDN`` allows modular design of advanced FDN structure with DSP operations in time and frequency domain.
 
+The source code is MIT-licensed. Small packaged tutorial resources retain the
+separate terms recorded in ``src/pyFDN/resources/ATTRIBUTION.md``; in
+particular, the Pori concert-hall impulse response is limited to
+noncommercial use.
+
 
 Highlights
 ----------

pyfdn-0.2.0/docs/__init__.py

@@ -0,0 +1 @@
+"""Documentation build helpers; this package is not distributed in the wheel."""

{pyfdn-0.1.0 → pyfdn-0.2.0}/docs/api_reference.rst

@@ -93,8 +93,11 @@ Acoustics & Absorption
    pyFDN.absorption_to_rt
    pyFDN.estimate_initial_level_bands
    pyFDN.estimate_rt_bands
+   pyFDN.octave_bands
+   pyFDN.octave_band_filterbank
    pyFDN.rt_to_gain_per_sample
    pyFDN.rt_to_slope
+   pyFDN.slope_amplitude_to_level
    pyFDN.slope_to_rt
 
 Graphic EQ
@@ -172,6 +175,7 @@ General Utilities
    pyFDN.lin_to_db
    pyFDN.sq_to_db
    pyFDN.ensure_3d
+   pyFDN.fade_out
    pyFDN.hertz_to_unit
    pyFDN.hertz_to_rad
    pyFDN.rad_to_hertz
@@ -181,10 +185,24 @@ General Utilities
    pyFDN.mulaw_decode
    pyFDN.mulaw_encode
    pyFDN.peak_normalize
-   pyFDN.load_audio
    pyFDN.pole_boundaries
    pyFDN.skew
 
+Packaged Examples & References
+------------------------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   pyFDN.available_audio
+   pyFDN.audio_metadata
+   pyFDN.load_audio
+   pyFDN.available_fdn_presets
+   pyFDN.load_fdn_preset
+   pyFDN.paper_reference
+   pyFDN.paper_link
+
 State-Space Translators
 -----------------------
 
@@ -194,6 +212,7 @@ State-Space Translators
 
    pyFDN.dss_to_ss
    pyFDN.dss_to_impz
+   pyFDN.build_to_impz
    pyFDN.dss_to_tf
    pyFDN.dss_to_pr
    pyFDN.dss_to_flamo
@@ -225,7 +244,7 @@ Training
 
    pyFDN.build_fdn
    pyFDN.trainable_from_build
-   pyFDN.with_decay
+   pyFDN.build_set_decay
    pyFDN.Trainable
    pyFDN.train_fdn
    pyFDN.TrainLog
@@ -252,6 +271,15 @@ Plotting
    pyFDN.downsample_minmax
    pyFDN.downsample_plotly_trace
 
+Notebook Display
+----------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   pyFDN.labeled_audio
+
 FLAMO Graph
 -----------
 

pyfdn-0.2.0/docs/audio_gallery.py

@@ -0,0 +1,150 @@
+"""Generate the audio gallery from the audio files packaged with pyFDN."""
+
+from __future__ import annotations
+
+import html
+import json
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import quote
+
+DOCS_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = DOCS_DIR.parent
+AUDIO_SOURCE_DIR = PROJECT_ROOT / "src" / "pyFDN" / "resources" / "audio"
+AUDIO_REFERENCES_FILE = AUDIO_SOURCE_DIR / "metadata.json"
+OUTPUT_FILE = DOCS_DIR / "audio_gallery.rst"
+GITHUB_AUDIO_ROOT = (
+    "https://raw.githubusercontent.com/artificial-audio/pyFDN/"
+    "main/src/pyFDN/resources/audio/"
+)
+
+UNCATEGORIZED = "uncategorized"
+
+
+@dataclass(frozen=True)
+class AudioExample:
+    path: Path
+    category: str
+
+    @property
+    def filename(self) -> str:
+        return self.path.name
+
+    @property
+    def display_label(self) -> str:
+        return f"{self.filename}"
+
+    @property
+    def audio_url(self) -> str:
+        relative = self.path.relative_to(AUDIO_SOURCE_DIR)
+        return GITHUB_AUDIO_ROOT + quote(relative.as_posix())
+
+
+def discover_audio_files() -> list[AudioExample]:
+    examples = []
+    for path in sorted(AUDIO_SOURCE_DIR.rglob("*.wav")):
+        relative = path.relative_to(AUDIO_SOURCE_DIR)
+        category = relative.parts[0] if len(relative.parts) > 1 else UNCATEGORIZED
+        examples.append(AudioExample(path, category))
+    return examples
+
+
+def render_gallery(examples: list[AudioExample]) -> str:
+    # Load audio metadata
+    with open(AUDIO_REFERENCES_FILE, encoding="utf-8") as f:
+        audio_references = {item["filename"]: item for item in json.load(f)}
+
+    grouped: dict[str, list[AudioExample]] = defaultdict(list)
+    for example in examples:
+        grouped[example.category].append(example)
+
+    categories = sorted(
+        grouped, key=lambda name: (name == UNCATEGORIZED, name.casefold())
+    )
+
+    lines = [
+        ".. This file is generated by docs/audio_gallery.py. Do not edit it manually.",
+        "",
+        "============",
+        "Audio Gallery",
+        "============",
+        "",
+        "Audio examples demonstrating ``pyFDN``. The gallery is generated",
+        "automatically from every packaged ``.wav`` file, grouped by resource category.",
+        "",
+    ]
+
+    for category in categories:
+        entries = sorted(grouped[category], key=lambda item: item.filename.casefold())
+
+        lines.extend(
+            [
+                category,
+                "-" * len(category),
+                "",
+                ".. raw:: html",
+                "",
+            ]
+        )
+
+        for example in entries:
+            label_html = html.escape(example.display_label)
+            src = example.audio_url
+
+            if example.filename in audio_references:
+                audio_ref = audio_references[example.filename]
+
+                title = html.escape(audio_ref["source"])
+                url = html.escape(audio_ref["source_url"])
+                creator = html.escape(audio_ref["creator"])
+                license_name = html.escape(audio_ref["license"])
+                license_url = html.escape(audio_ref["license_url"])
+
+                lines.extend(
+                    [
+                        f"   <p>{label_html}<br>",
+                        f'   Source: <a href="{url}">{title}</a> — {creator}<br>',
+                        f'   Terms: <a href="{license_url}">{license_name}</a><br>',
+                        "   <audio controls>",
+                        f'       <source src="{src}" type="audio/wav">',
+                        "       Your browser does not support the audio element.",
+                        "   </audio>",
+                        "   </p>",
+                    ]
+                )
+            else:
+                lines.extend(
+                    [
+                        f"   <p>{label_html}<br>",
+                        "   <audio controls>",
+                        f'       <source src="{src}" type="audio/wav">',
+                        "       Your browser does not support the audio element.",
+                        "   </audio>",
+                        "   </p>",
+                    ]
+                )
+
+        lines.append("")
+
+    lines.extend(
+        [
+            "----",
+            "",
+            "All audio files can also be browsed in the repository's",
+            "`packaged audio directory <https://github.com/artificial-audio/pyFDN/tree/main/src/pyFDN/resources/audio>`_.",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def generate_audio_gallery(output_file: Path = OUTPUT_FILE) -> str:
+    examples = discover_audio_files()
+    rendered = render_gallery(examples)
+    output_file.write_text(rendered, encoding="utf-8")
+    return rendered
+
+
+if __name__ == "__main__":
+    generate_audio_gallery()

pyfdn-0.2.0/docs/audio_gallery.rst

@@ -0,0 +1,99 @@
+.. This file is generated by docs/audio_gallery.py. Do not edit it manually.
+
+============
+Audio Gallery
+============
+
+Audio examples demonstrating ``pyFDN``. The gallery is generated
+automatically from every packaged ``.wav`` file, grouped by resource category.
+
+drums
+-----
+
+.. raw:: html
+
+   <p>drums.wav<br>
+   Source: <a href="https://github.com/artificial-audio/pyFDN">Original pyFDN drum example</a> — Sebastian J. Schlecht<br>
+   Terms: <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0-1.0</a><br>
+   <audio controls>
+       <source src="https://raw.githubusercontent.com/artificial-audio/pyFDN/main/src/pyFDN/resources/audio/drums/drums.wav" type="audio/wav">
+       Your browser does not support the audio element.
+   </audio>
+   </p>
+
+general
+-------
+
+.. raw:: html
+
+   <p>synth_dry.wav<br>
+   Source: <a href="https://github.com/artificial-audio/pyFDN">Original pyFDN synthesizer example</a> — Sebastian J. Schlecht<br>
+   Terms: <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0-1.0</a><br>
+   <audio controls>
+       <source src="https://raw.githubusercontent.com/artificial-audio/pyFDN/main/src/pyFDN/resources/audio/general/synth_dry.wav" type="audio/wav">
+       Your browser does not support the audio element.
+   </audio>
+   </p>
+
+rir
+---
+
+.. raw:: html
+
+   <p>s3_r4_o.wav<br>
+   Source: <a href="http://legacy.spa.aalto.fi/projects/poririrs/">Concert Hall Impulse Responses — Pori, Finland</a> — Juha Merimaa, Timo Peltonen, Tapio Lokki, Helsinki University of Technology, and Akukon Oy<br>
+   Terms: <a href="http://legacy.spa.aalto.fi/projects/poririrs/">PORIRIR noncommercial terms</a><br>
+   <audio controls>
+       <source src="https://raw.githubusercontent.com/artificial-audio/pyFDN/main/src/pyFDN/resources/audio/rir/s3_r4_o.wav" type="audio/wav">
+       Your browser does not support the audio element.
+   </audio>
+   </p>
+
+speech
+------
+
+.. raw:: html
+
+   <p>P1_Set1_8.wav<br>
+   Source: <a href="https://zenodo.org/records/15034732">Dataset of Audiovisual Speech for AR Telepresence Studies</a> — Nils Meyer-Kahlen, Anja Hofmann, Sebastian J. Schlecht, and Tapio Lokki<br>
+   Terms: <a href="https://zenodo.org/records/15034732">Included with creator permission</a><br>
+   <audio controls>
+       <source src="https://raw.githubusercontent.com/artificial-audio/pyFDN/main/src/pyFDN/resources/audio/speech/P1_Set1_8.wav" type="audio/wav">
+       Your browser does not support the audio element.
+   </audio>
+   </p>
+   <p>P20_Set1_8.wav<br>
+   Source: <a href="https://zenodo.org/records/15034732">Dataset of Audiovisual Speech for AR Telepresence Studies</a> — Nils Meyer-Kahlen, Anja Hofmann, Sebastian J. Schlecht, and Tapio Lokki<br>
+   Terms: <a href="https://zenodo.org/records/15034732">Included with creator permission</a><br>
+   <audio controls>
+       <source src="https://raw.githubusercontent.com/artificial-audio/pyFDN/main/src/pyFDN/resources/audio/speech/P20_Set1_8.wav" type="audio/wav">
+       Your browser does not support the audio element.
+   </audio>
+   </p>
+
+strings
+-------
+
+.. raw:: html
+
+   <p>Kleiderschrank_Taylor_DI.wav<br>
+   Source: <a href="https://phaidra.kug.ac.at/detail/o:68022">Gemeinfreie Gitarrenaufnahmen 1</a> — Franz Zotter and Daniel Rudrich<br>
+   Terms: <a href="https://creativecommons.org/publicdomain/mark/1.0/">PDM-1.0</a><br>
+   <audio controls>
+       <source src="https://raw.githubusercontent.com/artificial-audio/pyFDN/main/src/pyFDN/resources/audio/strings/Kleiderschrank_Taylor_DI.wav" type="audio/wav">
+       Your browser does not support the audio element.
+   </audio>
+   </p>
+   <p>Sommerhit2016_Taylor_DI.wav<br>
+   Source: <a href="https://phaidra.kug.ac.at/detail/o:68022">Gemeinfreie Gitarrenaufnahmen 1</a> — Franz Zotter and Daniel Rudrich<br>
+   Terms: <a href="https://creativecommons.org/publicdomain/mark/1.0/">PDM-1.0</a><br>
+   <audio controls>
+       <source src="https://raw.githubusercontent.com/artificial-audio/pyFDN/main/src/pyFDN/resources/audio/strings/Sommerhit2016_Taylor_DI.wav" type="audio/wav">
+       Your browser does not support the audio element.
+   </audio>
+   </p>
+
+----
+
+All audio files can also be browsed in the repository's
+`packaged audio directory <https://github.com/artificial-audio/pyFDN/tree/main/src/pyFDN/resources/audio>`_.

{pyfdn-0.1.0 → pyfdn-0.2.0}/docs/conf.py

@@ -9,12 +9,14 @@ sys.path.insert(
     0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src"))
 )
 
+from audio_gallery import generate_audio_gallery
 from example_gallery import generate_gallery  # noqa: E402
 
 import pyFDN  # noqa: E402
 
-# Keep the gallery in sync with every marimo notebook before Sphinx reads it.
+# Keep the gallery in sync with every marimo notebook and audio file before Sphinx reads it.
 generate_gallery()
+generate_audio_gallery()
 
 # -- Project information ------------------------------------------------------
 project = "pyFDN"

pyfdn-0.2.0/docs/example_gallery.py

@@ -0,0 +1,184 @@
+"""Generate the examples gallery from the marimo notebooks."""
+
+from __future__ import annotations
+
+import ast
+import re
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+
+DOCS_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = DOCS_DIR.parent
+EXAMPLES_DIR = PROJECT_ROOT / "examples"
+OUTPUT_FILE = DOCS_DIR / "examples_gallery.rst"
+
+CATEGORY_ORDER = (
+    "Getting Started",
+    "Absorption & Filters",
+    "Translation Examples",
+    "Allpass FDN Examples",
+    "Special FDNs",
+    "FDN Design & Analysis",
+)
+
+
+@dataclass(frozen=True)
+class Example:
+    path: Path
+    title: str
+    description: str
+    category: str
+
+    @property
+    def output_name(self) -> str:
+        relative = self.path.relative_to(EXAMPLES_DIR).with_suffix("")
+        return "_".join(relative.parts)
+
+
+def _markdown_blocks(path: Path) -> list[str]:
+    """Return literal Markdown strings passed to ``mo.md`` calls."""
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    blocks: list[str] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call) or not node.args:
+            continue
+        if not isinstance(node.func, ast.Attribute) or node.func.attr != "md":
+            continue
+        value = node.args[0]
+        if isinstance(value, ast.Constant) and isinstance(value.value, str):
+            blocks.append(value.value.strip())
+    return blocks
+
+
+def _plain_text(markdown: str) -> str:
+    text = re.sub(r"\[([^]]+)]\([^)]+\)", r"\1", markdown)
+    text = re.sub(r"`+([^`]+?)`+", r"``\1``", text)
+    text = re.sub(r"\*\*([^*]+)\*\*", r"\1", text)
+    text = re.sub(r"(?<!\*)\*([^*]+)\*(?!\*)", r"\1", text)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _title_and_description(path: Path) -> tuple[str, str]:
+    blocks = _markdown_blocks(path)
+    for block in blocks:
+        lines = block.splitlines()
+        for index, line in enumerate(lines):
+            if not line.startswith("# "):
+                continue
+            title = _plain_text(line[2:])
+            paragraphs = "\n".join(lines[index + 1 :]).strip().split("\n\n")
+            description = next(
+                (
+                    _plain_text(paragraph)
+                    for paragraph in paragraphs
+                    if paragraph.strip() and not paragraph.lstrip().startswith("#")
+                ),
+                "Open the rendered marimo notebook.",
+            )
+            return title, description
+
+    fallback = path.stem.removeprefix("example_").replace("_", " ").title()
+    return fallback, "Open the rendered marimo notebook."
+
+
+def _metadata(path: Path) -> dict[str, str]:
+    """Read ``# gallery_<key>: <value>`` comments."""
+    metadata: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines()[:20]:
+        match = re.match(r"# gallery_(\w+):\s*(.+)", line)
+        if match:
+            metadata[match.group(1)] = match.group(2).strip()
+    return metadata
+
+
+def _required_category(path: Path) -> str:
+    metadata = _metadata(path)
+    category = metadata.get("category")
+    if category:
+        return category
+    relative = path.relative_to(PROJECT_ROOT)
+    raise ValueError(f"{relative} is missing a required '# gallery_category: ...' tag")
+
+
+def discover_examples() -> list[Example]:
+    examples = []
+    for path in sorted(EXAMPLES_DIR.rglob("example_*.py")):
+        title, description = _title_and_description(path)
+        examples.append(
+            Example(
+                path,
+                title,
+                description,
+                _required_category(path),
+            )
+        )
+    return examples
+
+
+def render_gallery(examples: list[Example]) -> str:
+    grouped: dict[str, list[Example]] = defaultdict(list)
+    for example in examples:
+        grouped[example.category].append(example)
+
+    categories = list(CATEGORY_ORDER)
+    categories.extend(sorted(set(grouped) - set(categories)))
+
+    lines = [
+        ".. This file is generated by docs/example_gallery.py. Do not edit it manually.",
+        "",
+        "================",
+        "Examples Gallery",
+        "================",
+        "",
+        "Rendered Marimo notebooks demonstrating ``pyFDN``. The gallery is generated",
+        "automatically from every ``example_*.py`` file under ``examples/``.",
+        "",
+    ]
+
+    for category in categories:
+        entries = grouped.get(category, [])
+        if not entries:
+            continue
+        lines.extend(
+            [
+                category,
+                "-" * len(category),
+                "",
+                ".. list-table::",
+                "   :widths: 35 65",
+                "   :header-rows: 0",
+                "",
+            ]
+        )
+        for example in sorted(entries, key=lambda item: item.title.casefold()):
+            url = f"_static/marimo/notebooks/{example.output_name}.html"
+            lines.extend(
+                [
+                    f"   * - `{example.title} <{url}>`_",
+                    f"     - {example.description}",
+                ]
+            )
+        lines.append("")
+
+    lines.extend(
+        [
+            "----",
+            "",
+            "All notebooks can also be browsed in the repository's",
+            "`examples directory <https://github.com/artificial-audio/pyFDN/tree/main/examples>`_.",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def generate_gallery(output_file: Path = OUTPUT_FILE) -> str:
+    rendered = render_gallery(discover_examples())
+    output_file.write_text(rendered, encoding="utf-8")
+    return rendered
+
+
+if __name__ == "__main__":
+    generate_gallery()