plotwave 0.1.0__tar.gz

plotwave-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+name: Publish GitHub Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Sync dependencies
+        run: uv sync --all-groups
+
+      - name: Build demo site
+        run: uv run python scripts/build_pages_demo.py
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

plotwave-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.ipynb_checkpoints/
+dist/
+build/
+notebooks/*.html
+

plotwave-0.1.0/DEVELOPERS.md

@@ -0,0 +1,62 @@
+# Developer Guide
+
+## Setup
+
+From the project root:
+
+```bash
+uv sync --all-groups
+```
+
+## Main Commands
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Run lint:
+
+```bash
+uv run ruff check .
+```
+
+Run type-checking:
+
+```bash
+uv run mypy src
+```
+
+Run the example notebook:
+
+```bash
+uv run jupyter lab
+```
+
+Build the package:
+
+```bash
+uv build
+```
+
+## Typical Dev Loop
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run mypy src
+```
+
+## Project Layout
+
+- `src/plotwave/`: library code
+- `tests/`: automated tests
+- `examples/getting_started.ipynb`: user-facing notebook walkthrough
+- `examples/signal_helpers.py`: helper signals used by the examples
+
+## Notes
+
+- The package is installable with both `uv` and `pip`.
+- The notebook examples are meant for users; keep them focused on the public API.
+- If you change rendering or public behavior, update tests and the example notebook together.

plotwave-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Camil Ziane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plotwave-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: plotwave
+Version: 0.1.0
+Summary: Interactive audio and waveform plotting for notebooks and browsers.
+Project-URL: Homepage, https://github.com/camilziane/plotwave
+Project-URL: Repository, https://github.com/camilziane/plotwave
+Author: Camil Ziane
+License: MIT
+License-File: LICENSE
+Keywords: audio,jupyter,plotly,visualization,waveform
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Description-Content-Type: text/markdown
+
+# plotwave
+<p align="left">
+  <img src="https://raw.githubusercontent.com/camilziane/plotwave/main/assets/logo_name.png" alt="plotwave logo" width="200">
+</p>
+
+<p align="left">
+  Interactive Plotly waveforms with synchronized audio playback
+</p>
+
+<p align="left">
+  <a href="https://camilziane.github.io/plotwave/">Live interactive demo</a>
+</p>
+
+**Click anywhere in the waveform to hear the audio while inspecting it visually.  
+Overlay multiple audio tracks or add additional signals (labels, predictions, segmentation, scores) on top of the waveform.**
+
+Designed for **Jupyter notebooks**, `plotwave` can also be exported to **HTML**, making it easy to share interactive audio visualizations or log them in tools like **MLflow** for experiment analysis.
+
+## Install
+
+```bash
+uv add plotwave
+```
+
+or
+
+```bash
+pip install plotwave
+```
+
+## Smallest useful example
+
+```python
+import soundfile as sf
+import plotwave
+
+wav, sr = sf.read("wave.wav", always_2d=False)
+
+plotwave.plot(wav, sr=sr, name="voice")
+```
+
+`soundfile` is only used here as a convenient audio loader. `plotwave` itself only depends on `numpy`.
+
+## Audio + curve
+
+```python
+env = np.abs(wav)
+
+plotwave.plot(
+    [
+        plotwave.audio(wav, sr, name="audio", color="#2563eb"),
+        plotwave.series(env, name="envelope", color="#f97316", fill="tozeroy"),
+    ],
+    layout={"title": {"text": "Audio + envelope"}, "height": 520},
+)
+```
+
+If `series(..., time=None)` is plotted next to audio, `plotwave` infers its time axis automatically when the audio timing is unambiguous.
+
+## Segments
+
+```python
+plotwave.plot(
+    [
+        plotwave.audio(wav, sr, name="audio"),
+        plotwave.segments(
+            [
+                {"start": 0.0, "end": 0.7, "label": "Bm"},
+                {"start": 1.0, "end": 1.6, "label": "G"},
+            ],
+            name="Pred",
+            lane="top",
+            color_map={"Bm": "#2563eb", "G": "#16a34a"},
+        ),
+    ]
+)
+```
+
+`segments(...)` adds:
+
+- colored background blocks
+- label boxes
+- hoverable segment names
+- top/bottom lanes for comparisons like prediction vs ground truth
+
+## Export
+
+```python
+plot = plotwave.plot(wav, sr=sr)
+plot.save("wave.html")
+html = plot.html()
+```
+
+## API
+
+Public API:
+
+- `plotwave.plot(...)`
+- `plotwave.audio(...)`
+- `plotwave.series(...)`
+- `plotwave.segments(...)`
+- `plotwave.Plot`
+
+See [examples/getting_started.ipynb](https://github.com/camilziane/plotwave/blob/main/examples/getting_started.ipynb) for a full walkthrough.
+
+Developer workflow: [DEVELOPERS.md](https://github.com/camilziane/plotwave/blob/main/DEVELOPERS.md)
+
+To refresh the GitHub Pages demo locally:
+
+```bash
+uv run python scripts/build_pages_demo.py
+```

plotwave-0.1.0/README.md

@@ -0,0 +1,112 @@
+# plotwave
+<p align="left">
+  <img src="https://raw.githubusercontent.com/camilziane/plotwave/main/assets/logo_name.png" alt="plotwave logo" width="200">
+</p>
+
+<p align="left">
+  Interactive Plotly waveforms with synchronized audio playback
+</p>
+
+<p align="left">
+  <a href="https://camilziane.github.io/plotwave/">Live interactive demo</a>
+</p>
+
+**Click anywhere in the waveform to hear the audio while inspecting it visually.  
+Overlay multiple audio tracks or add additional signals (labels, predictions, segmentation, scores) on top of the waveform.**
+
+Designed for **Jupyter notebooks**, `plotwave` can also be exported to **HTML**, making it easy to share interactive audio visualizations or log them in tools like **MLflow** for experiment analysis.
+
+## Install
+
+```bash
+uv add plotwave
+```
+
+or
+
+```bash
+pip install plotwave
+```
+
+## Smallest useful example
+
+```python
+import soundfile as sf
+import plotwave
+
+wav, sr = sf.read("wave.wav", always_2d=False)
+
+plotwave.plot(wav, sr=sr, name="voice")
+```
+
+`soundfile` is only used here as a convenient audio loader. `plotwave` itself only depends on `numpy`.
+
+## Audio + curve
+
+```python
+env = np.abs(wav)
+
+plotwave.plot(
+    [
+        plotwave.audio(wav, sr, name="audio", color="#2563eb"),
+        plotwave.series(env, name="envelope", color="#f97316", fill="tozeroy"),
+    ],
+    layout={"title": {"text": "Audio + envelope"}, "height": 520},
+)
+```
+
+If `series(..., time=None)` is plotted next to audio, `plotwave` infers its time axis automatically when the audio timing is unambiguous.
+
+## Segments
+
+```python
+plotwave.plot(
+    [
+        plotwave.audio(wav, sr, name="audio"),
+        plotwave.segments(
+            [
+                {"start": 0.0, "end": 0.7, "label": "Bm"},
+                {"start": 1.0, "end": 1.6, "label": "G"},
+            ],
+            name="Pred",
+            lane="top",
+            color_map={"Bm": "#2563eb", "G": "#16a34a"},
+        ),
+    ]
+)
+```
+
+`segments(...)` adds:
+
+- colored background blocks
+- label boxes
+- hoverable segment names
+- top/bottom lanes for comparisons like prediction vs ground truth
+
+## Export
+
+```python
+plot = plotwave.plot(wav, sr=sr)
+plot.save("wave.html")
+html = plot.html()
+```
+
+## API
+
+Public API:
+
+- `plotwave.plot(...)`
+- `plotwave.audio(...)`
+- `plotwave.series(...)`
+- `plotwave.segments(...)`
+- `plotwave.Plot`
+
+See [examples/getting_started.ipynb](https://github.com/camilziane/plotwave/blob/main/examples/getting_started.ipynb) for a full walkthrough.
+
+Developer workflow: [DEVELOPERS.md](https://github.com/camilziane/plotwave/blob/main/DEVELOPERS.md)
+
+To refresh the GitHub Pages demo locally:
+
+```bash
+uv run python scripts/build_pages_demo.py
+```