@molecule/app-feature-audio-waveform-vue 0.0.1-stage → 1.1.0
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.
- package/README.md +257 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,264 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-11-21T12:46:28.075Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-feature-audio-waveform-vue
|
|
2
10
|
|
|
3
|
-
|
|
11
|
+
Audio waveform — stylized SVG renderer of pre-computed audio peaks
|
|
12
|
+
with progress overlay, click-to-seek, and timed region markers.
|
|
13
|
+
|
|
14
|
+
Vue counterpart of `@molecule/app-feature-audio-waveform-react`: the same
|
|
15
|
+
props (React names), the same DOM for the same input.
|
|
16
|
+
|
|
17
|
+
Used by music-daw, podcast, and music-streaming surfaces to display
|
|
18
|
+
a waveform of the underlying audio source. Peak amplitudes must be
|
|
19
|
+
computed by the caller (typically offline with `wavesurfer.js`,
|
|
20
|
+
`peaks.js`, or an `AudioContext` analysis pass) — this package is
|
|
21
|
+
intentionally just the renderer.
|
|
22
|
+
|
|
23
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
24
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
25
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
26
|
+
|
|
27
|
+
## Quick Start
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import { defineComponent, h } from 'vue'
|
|
31
|
+
import { AudioWaveform } from '@molecule/app-feature-audio-waveform-vue'
|
|
32
|
+
|
|
33
|
+
const Player = defineComponent({
|
|
34
|
+
props: { peaks: Array, duration: Number, currentTime: Number },
|
|
35
|
+
setup(props) {
|
|
36
|
+
return () =>
|
|
37
|
+
h(AudioWaveform, {
|
|
38
|
+
peaks: props.peaks,
|
|
39
|
+
duration: props.duration,
|
|
40
|
+
currentTime: props.currentTime,
|
|
41
|
+
onSeek: (seconds: number) => {
|
|
42
|
+
// move the audio element to `seconds`
|
|
43
|
+
},
|
|
44
|
+
regions: [{ id: 'loop', startTime: 12, duration: 3, color: '#a78bfa55' }],
|
|
45
|
+
})
|
|
46
|
+
},
|
|
47
|
+
})
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Type
|
|
51
|
+
|
|
52
|
+
`feature`
|
|
53
|
+
|
|
54
|
+
## Installation
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm install @molecule/app-feature-audio-waveform-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## API
|
|
61
|
+
|
|
62
|
+
### Interfaces
|
|
63
|
+
|
|
64
|
+
#### `WaveformRegion`
|
|
65
|
+
|
|
66
|
+
A timed colored band overlaid on top of the waveform — used to mark
|
|
67
|
+
loop ranges, comments, edit selections, chapter spans, etc.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
interface WaveformRegion {
|
|
71
|
+
/** Stable identifier for the region (used as a render key). */
|
|
72
|
+
id: string
|
|
73
|
+
/** Start of the region, in seconds. */
|
|
74
|
+
startTime: number
|
|
75
|
+
/** Duration of the region, in seconds. Negative / zero hides the region. */
|
|
76
|
+
duration: number
|
|
77
|
+
/**
|
|
78
|
+
* Optional CSS color applied to the region rectangle. Defaults to a
|
|
79
|
+
* semi-transparent accent ink. Use semi-transparent fills so the
|
|
80
|
+
* underlying waveform stays visible.
|
|
81
|
+
*/
|
|
82
|
+
color?: string
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
#### `AudioWaveformProps`
|
|
87
|
+
|
|
88
|
+
AudioWaveform component props (React's prop names).
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
interface AudioWaveformProps {
|
|
92
|
+
/**
|
|
93
|
+
* Pre-computed peak amplitudes in playback order. Each value should
|
|
94
|
+
* be normalized into the closed interval `[0, 1]` (the renderer clamps
|
|
95
|
+
* out-of-range values). One bar is drawn per peak.
|
|
96
|
+
*/
|
|
97
|
+
peaks: number[]
|
|
98
|
+
/**
|
|
99
|
+
* Total duration of the underlying audio in seconds. Used to translate
|
|
100
|
+
* click positions into seek timestamps and to size region overlays.
|
|
101
|
+
* Must be `> 0` for `onSeek` and `regions` to render correctly.
|
|
102
|
+
*/
|
|
103
|
+
duration: number
|
|
104
|
+
/**
|
|
105
|
+
* Current playback time in seconds. Drives the progress overlay that
|
|
106
|
+
* fills the waveform from the left up to this point. Defaults to `0`.
|
|
107
|
+
*/
|
|
108
|
+
currentTime?: number
|
|
109
|
+
/**
|
|
110
|
+
* Optional click handler called with the seek target time (in
|
|
111
|
+
* seconds) when the user clicks anywhere on the waveform. When
|
|
112
|
+
* omitted, the waveform renders as a non-interactive display.
|
|
113
|
+
*/
|
|
114
|
+
onSeek?: (seekTime: number) => void
|
|
115
|
+
/** Optional region markers overlaid on top of the waveform. */
|
|
116
|
+
regions?: WaveformRegion[]
|
|
117
|
+
/** Pixel height of the waveform. Defaults to `64`. */
|
|
118
|
+
height?: number
|
|
119
|
+
/**
|
|
120
|
+
* CSS color used for the progress overlay (the played portion of the
|
|
121
|
+
* waveform). Defaults to `currentColor`.
|
|
122
|
+
*/
|
|
123
|
+
progressColor?: string
|
|
124
|
+
/**
|
|
125
|
+
* CSS color used for the unplayed portion of the waveform. Defaults
|
|
126
|
+
* to `currentColor`.
|
|
127
|
+
*/
|
|
128
|
+
waveColor?: string
|
|
129
|
+
/** Extra classes merged onto the root element. */
|
|
130
|
+
className?: string
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Functions
|
|
4
135
|
|
|
136
|
+
#### `clamp(value, min, max)`
|
|
137
|
+
|
|
138
|
+
Clamp a value into the closed interval `[min, max]`. Returns `min`
|
|
139
|
+
for `NaN` / non-finite inputs.
|
|
140
|
+
|
|
141
|
+
```typescript
|
|
142
|
+
function clamp(value: number, min: number, max: number): number
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
- `value` — Value to clamp.
|
|
146
|
+
- `min` — Minimum (inclusive).
|
|
147
|
+
- `max` — Maximum (inclusive).
|
|
148
|
+
|
|
149
|
+
**Returns:** The clamped value.
|
|
150
|
+
|
|
151
|
+
#### `seekTimeFromClick(x, width, duration)`
|
|
152
|
+
|
|
153
|
+
Compute the seek time (in seconds) for a click at horizontal pixel
|
|
154
|
+
`x` inside a waveform bounding box of `width` pixels covering an
|
|
155
|
+
audio of `duration` seconds. Clamps the result into `[0, duration]`.
|
|
156
|
+
|
|
157
|
+
```typescript
|
|
158
|
+
function seekTimeFromClick(x: number, width: number, duration: number): number
|
|
5
159
|
```
|
|
6
|
-
|
|
160
|
+
|
|
161
|
+
- `x` — Horizontal pixel offset of the click inside the bounding box.
|
|
162
|
+
- `width` — Width of the bounding box in pixels.
|
|
163
|
+
- `duration` — Total audio duration in seconds.
|
|
164
|
+
|
|
165
|
+
**Returns:** The seek target time, in seconds.
|
|
166
|
+
|
|
167
|
+
### Constants
|
|
168
|
+
|
|
169
|
+
#### `AudioWaveform`
|
|
170
|
+
|
|
171
|
+
Stylized SVG audio waveform with click-to-seek + region overlays.
|
|
172
|
+
Renders pre-computed peak amplitudes as vertical bars centered on a
|
|
173
|
+
baseline. A progress overlay fills the played portion from the left;
|
|
174
|
+
region markers render as colored rectangles spanning their time range.
|
|
175
|
+
|
|
176
|
+
All styling routes through `getClassMap()` and all user-visible text
|
|
177
|
+
routes through `t()` so the waveform translates via the companion
|
|
178
|
+
`@molecule/app-locales-feature-audio-waveform` locale bond.
|
|
179
|
+
|
|
180
|
+
```typescript
|
|
181
|
+
const AudioWaveform: DefineComponent<
|
|
182
|
+
ExtractPropTypes<{
|
|
183
|
+
peaks: { type: PropType<number[]>; required: true }
|
|
184
|
+
duration: { type: NumberConstructor; required: true }
|
|
185
|
+
currentTime: { type: NumberConstructor; default: number }
|
|
186
|
+
onSeek: { type: PropType<(seekTime: number) => void>; default: undefined }
|
|
187
|
+
regions: { type: PropType<WaveformRegion[]>; default: undefined }
|
|
188
|
+
height: { type: NumberConstructor; default: number }
|
|
189
|
+
progressColor: { type: StringConstructor; default: undefined }
|
|
190
|
+
waveColor: { type: StringConstructor; default: undefined }
|
|
191
|
+
className: { type: StringConstructor; default: undefined }
|
|
192
|
+
}>,
|
|
193
|
+
() => VNode,
|
|
194
|
+
{},
|
|
195
|
+
{},
|
|
196
|
+
{},
|
|
197
|
+
ComponentOptionsMixin,
|
|
198
|
+
ComponentOptionsMixin,
|
|
199
|
+
{},
|
|
200
|
+
string,
|
|
201
|
+
PublicProps,
|
|
202
|
+
Readonly<
|
|
203
|
+
ExtractPropTypes<{
|
|
204
|
+
peaks: { type: PropType<number[]>; required: true }
|
|
205
|
+
duration: { type: NumberConstructor; required: true }
|
|
206
|
+
currentTime: { type: NumberConstructor; default: number }
|
|
207
|
+
onSeek: { type: PropType<(seekTime: number) => void>; default: undefined }
|
|
208
|
+
regions: { type: PropType<WaveformRegion[]>; default: undefined }
|
|
209
|
+
height: { type: NumberConstructor; default: number }
|
|
210
|
+
progressColor: { type: StringConstructor; default: undefined }
|
|
211
|
+
waveColor: { type: StringConstructor; default: undefined }
|
|
212
|
+
className: { type: StringConstructor; default: undefined }
|
|
213
|
+
}>
|
|
214
|
+
> &
|
|
215
|
+
Readonly<{}>,
|
|
216
|
+
{
|
|
217
|
+
currentTime: number
|
|
218
|
+
onSeek: (seekTime: number) => void
|
|
219
|
+
regions: WaveformRegion[]
|
|
220
|
+
height: number
|
|
221
|
+
progressColor: string
|
|
222
|
+
waveColor: string
|
|
223
|
+
className: string
|
|
224
|
+
},
|
|
225
|
+
{},
|
|
226
|
+
{},
|
|
227
|
+
{},
|
|
228
|
+
string,
|
|
229
|
+
ComponentProvideOptions,
|
|
230
|
+
true,
|
|
231
|
+
{},
|
|
232
|
+
any
|
|
233
|
+
>
|
|
7
234
|
```
|
|
8
235
|
|
|
9
|
-
|
|
236
|
+
- `props` — Component props (see {@link AudioWaveformProps}).
|
|
237
|
+
|
|
238
|
+
**Returns:** The audio-waveform element.
|
|
239
|
+
|
|
240
|
+
## Injection Notes
|
|
241
|
+
|
|
242
|
+
### Requirements
|
|
243
|
+
|
|
244
|
+
Peer dependencies:
|
|
245
|
+
|
|
246
|
+
- `@molecule/app-ui` ^1.0.1
|
|
247
|
+
- `@molecule/app-ui-vue` ^1.1.0
|
|
248
|
+
- `@molecule/app-vue` ^3.5.0
|
|
249
|
+
- `vue` ^3.4.0
|
|
250
|
+
|
|
251
|
+
### Runtime Dependencies
|
|
252
|
+
|
|
253
|
+
- `@molecule/app-ui`
|
|
254
|
+
- `@molecule/app-ui-vue`
|
|
255
|
+
- `@molecule/app-vue`
|
|
256
|
+
- `vue`
|
|
257
|
+
|
|
258
|
+
- Requires a bonded ClassMap — rendering throws otherwise.
|
|
259
|
+
- Text (aria labels + the empty state) routes through the binding's
|
|
260
|
+
`useTranslation()`, so a locale switch re-renders it.
|
|
261
|
+
|
|
262
|
+
## Translations
|
|
10
263
|
|
|
11
|
-
|
|
264
|
+
Translation strings are provided by `@molecule/app-locales-feature-audio-waveform`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-feature-audio-waveform-vue",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Stylized SVG audio waveform with click-to-seek + region overlays — renders pre-computed peaks for music-daw / podcast / streaming",
|
|
5
5
|
"homepage": "https://www.molecule.dev/packages/app-feature-audio-waveform-vue",
|
|
6
6
|
"type": "module",
|
|
@@ -55,9 +55,9 @@
|
|
|
55
55
|
"@molecule/app-framework-conformance": "0.0.0",
|
|
56
56
|
"@molecule/app-i18n": "1.2.2",
|
|
57
57
|
"@molecule/app-icons": "1.0.4",
|
|
58
|
-
"@molecule/app-ui": "1.
|
|
59
|
-
"@molecule/app-ui-vue": "1.1
|
|
60
|
-
"@molecule/app-vue": "3.
|
|
58
|
+
"@molecule/app-ui": "1.5.0",
|
|
59
|
+
"@molecule/app-ui-vue": "1.2.1",
|
|
60
|
+
"@molecule/app-vue": "3.9.0",
|
|
61
61
|
"@types/node": "26.6.5",
|
|
62
62
|
"jsdom": "30.1.3",
|
|
63
63
|
"typescript": "6.0.3",
|