plotwave 0.1.0__tar.gz → 0.1.2__tar.gz

{plotwave-0.1.0 → plotwave-0.1.2}/.gitignore

@@ -9,4 +9,9 @@ __pycache__/
 dist/
 build/
 notebooks/*.html
-
+notebook_test
+plotwave-assets/
+docs/*.png
+docs/*.svg
+docs/*.ico
+docs/*.webmanifest

{plotwave-0.1.0 → plotwave-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotwave
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -18,7 +18,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.11
+Requires-Dist: lameenc>=1.8.2
 Requires-Dist: numpy>=1.26
+Requires-Dist: soundfile>=0.12.1
 Description-Content-Type: text/markdown
 
 # plotwave
@@ -39,6 +41,14 @@ Overlay multiple audio tracks or add additional signals (labels, predictions, se
 
 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.
 
+## Why plotwave
+
+- Start from a path with `plotwave.audio_file(...)` and get an interactive waveform without manually decoding audio first.
+- Click anywhere in the waveform to audition the exact moment you are inspecting.
+- Click a segment label to loop that labeled region and compare it against the waveform.
+- Overlay predictions, envelopes, scores, or ground-truth labels on the same timeline.
+- Use the same interaction model in notebooks and exported HTML.
+
 ## Install
 
 ```bash
@@ -51,41 +61,51 @@ or
 pip install plotwave
 ```
 
-## Smallest useful example
+## Direct audio file example
 
 ```python
-import soundfile as sf
 import plotwave
 
-wav, sr = sf.read("wave.wav", always_2d=False)
-
-plotwave.plot(wav, sr=sr, name="voice")
+plotwave.audio_file("voice.mp3", name="voice").plot(
+    layout={"title": {"text": "Direct file-backed audio"}, "height": 460},
+)
 ```
 
-`soundfile` is only used here as a convenient audio loader. `plotwave` itself only depends on `numpy`.
+`plotwave.audio_file(...)` uses `soundfile` internally and can open any local audio format that your `soundfile` backend supports, including WAV and MP3. It is the quickest way to go from a local audio file to an interactive player + waveform view.
+Use `soundfile.read(...)` only when you want to derive an extra trace from the samples, like an envelope or model scores.
 
 ## Audio + curve
 
 ```python
+import numpy as np
+import soundfile as sf
+import plotwave
+
+wav, sr = sf.read("voice.mp3", always_2d=False)
 env = np.abs(wav)
 
 plotwave.plot(
     [
-        plotwave.audio(wav, sr, name="audio", color="#2563eb"),
-        plotwave.series(env, name="envelope", color="#f97316", fill="tozeroy"),
+        plotwave.audio_file("voice.mp3", name="audio", color="#2563eb"),
+        plotwave.series(env, sr=sr, 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.
+For `series(...)`, use:
 
-## Segments
+- `sr=...` when your values are evenly sampled
+- `time=...` when you already have an explicit time axis
+
+## Segments and label looping
 
 ```python
+import plotwave
+
 plotwave.plot(
     [
-        plotwave.audio(wav, sr, name="audio"),
+        plotwave.audio_file("song.mp3", name="audio"),
         plotwave.segments(
             [
                 {"start": 0.0, "end": 0.7, "label": "Bm"},
@@ -101,8 +121,8 @@ plotwave.plot(
 
 `segments(...)` adds:
 
+- clickable label boxes that loop the matching audio span
 - colored background blocks
-- label boxes
 - hoverable segment names
 - top/bottom lanes for comparisons like prediction vs ground truth
 
@@ -114,16 +134,26 @@ plot.save("wave.html")
 html = plot.html()
 ```
 
+By default, notebook output, `html()`, and `save()` use compressed audio. You can disable that and control the bitrate explicitly:
+
+```python
+plot = plotwave.audio_file("voice.mp3").plot(compress_audio=False)
+html = plot.html(compress_audio=True, bitrate="48k")
+```
+
 ## API
 
 Public API:
 
 - `plotwave.plot(...)`
 - `plotwave.audio(...)`
+- `plotwave.audio_file(...)`
 - `plotwave.series(...)`
 - `plotwave.segments(...)`
 - `plotwave.Plot`
 
+All trace types also have `trace.plot(...)` as a shortcut for `plotwave.plot(trace, ...)`.
+
 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)

{plotwave-0.1.0 → plotwave-0.1.2}/README.md

@@ -16,6 +16,14 @@ Overlay multiple audio tracks or add additional signals (labels, predictions, se
 
 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.
 
+## Why plotwave
+
+- Start from a path with `plotwave.audio_file(...)` and get an interactive waveform without manually decoding audio first.
+- Click anywhere in the waveform to audition the exact moment you are inspecting.
+- Click a segment label to loop that labeled region and compare it against the waveform.
+- Overlay predictions, envelopes, scores, or ground-truth labels on the same timeline.
+- Use the same interaction model in notebooks and exported HTML.
+
 ## Install
 
 ```bash
@@ -28,41 +36,51 @@ or
 pip install plotwave
 ```
 
-## Smallest useful example
+## Direct audio file example
 
 ```python
-import soundfile as sf
 import plotwave
 
-wav, sr = sf.read("wave.wav", always_2d=False)
-
-plotwave.plot(wav, sr=sr, name="voice")
+plotwave.audio_file("voice.mp3", name="voice").plot(
+    layout={"title": {"text": "Direct file-backed audio"}, "height": 460},
+)
 ```
 
-`soundfile` is only used here as a convenient audio loader. `plotwave` itself only depends on `numpy`.
+`plotwave.audio_file(...)` uses `soundfile` internally and can open any local audio format that your `soundfile` backend supports, including WAV and MP3. It is the quickest way to go from a local audio file to an interactive player + waveform view.
+Use `soundfile.read(...)` only when you want to derive an extra trace from the samples, like an envelope or model scores.
 
 ## Audio + curve
 
 ```python
+import numpy as np
+import soundfile as sf
+import plotwave
+
+wav, sr = sf.read("voice.mp3", always_2d=False)
 env = np.abs(wav)
 
 plotwave.plot(
     [
-        plotwave.audio(wav, sr, name="audio", color="#2563eb"),
-        plotwave.series(env, name="envelope", color="#f97316", fill="tozeroy"),
+        plotwave.audio_file("voice.mp3", name="audio", color="#2563eb"),
+        plotwave.series(env, sr=sr, 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.
+For `series(...)`, use:
 
-## Segments
+- `sr=...` when your values are evenly sampled
+- `time=...` when you already have an explicit time axis
+
+## Segments and label looping
 
 ```python
+import plotwave
+
 plotwave.plot(
     [
-        plotwave.audio(wav, sr, name="audio"),
+        plotwave.audio_file("song.mp3", name="audio"),
         plotwave.segments(
             [
                 {"start": 0.0, "end": 0.7, "label": "Bm"},
@@ -78,8 +96,8 @@ plotwave.plot(
 
 `segments(...)` adds:
 
+- clickable label boxes that loop the matching audio span
 - colored background blocks
-- label boxes
 - hoverable segment names
 - top/bottom lanes for comparisons like prediction vs ground truth
 
@@ -91,16 +109,26 @@ plot.save("wave.html")
 html = plot.html()
 ```
 
+By default, notebook output, `html()`, and `save()` use compressed audio. You can disable that and control the bitrate explicitly:
+
+```python
+plot = plotwave.audio_file("voice.mp3").plot(compress_audio=False)
+html = plot.html(compress_audio=True, bitrate="48k")
+```
+
 ## API
 
 Public API:
 
 - `plotwave.plot(...)`
 - `plotwave.audio(...)`
+- `plotwave.audio_file(...)`
 - `plotwave.series(...)`
 - `plotwave.segments(...)`
 - `plotwave.Plot`
 
+All trace types also have `trace.plot(...)` as a shortcut for `plotwave.plot(trace, ...)`.
+
 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)