@untemps/vocal 2.0.0-beta.2 → 2.0.0-beta.20

package/CHANGELOG.md

@@ -1,3 +1,146 @@
+# [2.0.0-beta.20](https://github.com/untemps/vocal/compare/v2.0.0-beta.19...v2.0.0-beta.20) (2026-05-20)
+
+
+### Features
+
+* Auto-restart recognition on silence in continuous mode ([#84](https://github.com/untemps/vocal/issues/84)) ([79a55f5](https://github.com/untemps/vocal/commit/79a55f5e295d2027a1473ce59872e6a09b4655c1))
+
+
+### BREAKING CHANGES
+
+* continuous mode now keeps the session alive across silence and aggregates results — semantics that callers using `continuous: true` must adapt to:
+- Recording no longer ends after ~7s of silence; call `stop()` or `abort()` explicitly to terminate the session.
+- A synthetic `result` event is emitted just before `end` on `stop()`, carrying the joined final transcripts. `event instanceof SpeechRecognitionEvent` returns `false` for this event — read the transcript through the listener's second argument (`(event, bestAlternative, alternatives) => ...`).
+- Intermediate `end` and `start` events fired by the browser during silent restart cycles are no longer forwarded to user listeners. `isRecording` stays `true` across the cycle.
+- `abort()` discards the aggregated buffer without emitting.
+`continuous: false` consumers see no behavioural change.
+
+# [2.0.0-beta.19](https://github.com/untemps/vocal/compare/v2.0.0-beta.18...v2.0.0-beta.19) (2026-05-17)
+
+# [2.0.0-beta.18](https://github.com/untemps/vocal/compare/v2.0.0-beta.17...v2.0.0-beta.18) (2026-05-16)
+
+
+### chore
+
+* Remove UMD bundle from distribution ([#78](https://github.com/untemps/vocal/issues/78)) ([c0c819c](https://github.com/untemps/vocal/commit/c0c819c251cf4ee838463bf9dd6a960a70f6ad32))
+
+
+### BREAKING CHANGES
+
+* dist/index.umd.js is no longer published. Consumers loading via <script> tags or AMD loaders should use dist/index.es.js with a module-aware loader instead.
+
+# [2.0.0-beta.17](https://github.com/untemps/vocal/compare/v2.0.0-beta.16...v2.0.0-beta.17) (2026-05-16)
+
+
+### Features
+
+* Remove instance getter to prevent implementation leakage ([#77](https://github.com/untemps/vocal/issues/77)) ([93fc58f](https://github.com/untemps/vocal/commit/93fc58f46abe7fadced9c8f512dd69fb4865cd9c))
+
+
+### BREAKING CHANGES
+
+* vocal.instance is removed. Consumers who accessed the raw SpeechRecognition object must migrate to Vocal API methods.
+
+# [2.0.0-beta.16](https://github.com/untemps/vocal/compare/v2.0.0-beta.15...v2.0.0-beta.16) (2026-05-16)
+
+
+### Features
+
+* Add once() method for one-shot event listener registration ([#76](https://github.com/untemps/vocal/issues/76)) ([8179643](https://github.com/untemps/vocal/commit/8179643f159e3ccf690f7ac2d8bd101568c6e5b3))
+
+# [2.0.0-beta.15](https://github.com/untemps/vocal/compare/v2.0.0-beta.14...v2.0.0-beta.15) (2026-05-16)
+
+
+### Features
+
+* Support multiple listeners per event type in addEventListener ([#75](https://github.com/untemps/vocal/issues/75)) ([97a435d](https://github.com/untemps/vocal/commit/97a435dc09105fadb9d8c22052ddaa75cbb6ee26))
+
+
+### BREAKING CHANGES
+
+* addEventListener now stacks listeners instead of replacing. removeEventListener(eventType) removes all handlers for the type
+removeEventListener(eventType, callback) removes only the specific callback.
+
+# [2.0.0-beta.14](https://github.com/untemps/vocal/compare/v2.0.0-beta.13...v2.0.0-beta.14) (2026-05-16)
+
+# [2.0.0-beta.13](https://github.com/untemps/vocal/compare/v2.0.0-beta.12...v2.0.0-beta.13) (2026-05-16)
+
+# [2.0.0-beta.12](https://github.com/untemps/vocal/compare/v2.0.0-beta.11...v2.0.0-beta.12) (2026-05-16)
+
+# [2.0.0-beta.11](https://github.com/untemps/vocal/compare/v2.0.0-beta.10...v2.0.0-beta.11) (2026-05-16)
+
+
+### Bug Fixes
+
+* Throw on invalid event type in addEventListener and removeEventListener ([#69](https://github.com/untemps/vocal/issues/69)) ([a474718](https://github.com/untemps/vocal/commit/a474718fc7f36e4828a5430cf7c19b851401189d))
+
+# [2.0.0-beta.10](https://github.com/untemps/vocal/compare/v2.0.0-beta.9...v2.0.0-beta.10) (2026-05-16)
+
+
+### Bug Fixes
+
+* Remove internal end listener on cleanup ([#68](https://github.com/untemps/vocal/issues/68)) ([3179943](https://github.com/untemps/vocal/commit/31799433b054cca334d6159d8aae9e00c8971b6d))
+
+# [2.0.0-beta.9](https://github.com/untemps/vocal/compare/v2.0.0-beta.8...v2.0.0-beta.9) (2026-05-16)
+
+# [2.0.0-beta.8](https://github.com/untemps/vocal/compare/v2.0.0-beta.7...v2.0.0-beta.8) (2026-05-16)
+
+
+### Bug Fixes
+
+* Return false from isSupported in non-browser environments ([#65](https://github.com/untemps/vocal/issues/65)) ([56f67cc](https://github.com/untemps/vocal/commit/56f67cc6cc9ff6288472d1461a71d3e0cbc128ed))
+
+# [2.0.0-beta.7](https://github.com/untemps/vocal/compare/v2.0.0-beta.6...v2.0.0-beta.7) (2026-05-16)
+
+
+### Bug Fixes
+
+* Use resultIndex to select current result in continuous mode ([#64](https://github.com/untemps/vocal/issues/64)) ([62d61c4](https://github.com/untemps/vocal/commit/62d61c41ec7713cb01d578568b462734324e722a))
+
+# [2.0.0-beta.6](https://github.com/untemps/vocal/compare/v2.0.0-beta.5...v2.0.0-beta.6) (2026-05-16)
+
+
+### chore
+
+* Add type module and rename CJS dist to index.cjs ([#45](https://github.com/untemps/vocal/issues/45)) ([e9923af](https://github.com/untemps/vocal/commit/e9923af7032fe48fc0b214bb77e3d6708a4b1adb))
+
+
+### BREAKING CHANGES
+
+* "main" field: dist/index.js → dist/index.cjs. Consumers using the main field directly (not via the exports map) must update their import path.
+Consumers using the exports map (require/import conditions) are not affected.
+
+# [2.0.0-beta.5](https://github.com/untemps/vocal/compare/v2.0.0-beta.4...v2.0.0-beta.5) (2026-05-16)
+
+
+* refactor!: Select best RESULT transcript by confidence ([#44](https://github.com/untemps/vocal/issues/44)) ([4713366](https://github.com/untemps/vocal/commit/471336641a156623a17b6f7e0602658a3086381d))
+
+
+### BREAKING CHANGES
+
+* The RESULT callback signature changes from (event, transcript: string, alternatives: string[]) to (event, bestAlternative: string, alternatives: string[]) where bestAlternative is the alternative with the highest confidence score instead of the first in the array.
+Migration: no change needed if confidence ordering matches array order (standard browser behavior); replace transcript with bestAlternative if using the parameter name.
+
+# [2.0.0-beta.4](https://github.com/untemps/vocal/compare/v2.0.0-beta.3...v2.0.0-beta.4) (2026-05-16)
+
+
+### Features
+
+* start() rejects on error instead of always resolving ([#43](https://github.com/untemps/vocal/issues/43)) ([4414f11](https://github.com/untemps/vocal/commit/4414f11608e795b94845d06e6be53e8e5a76e022))
+
+
+### BREAKING CHANGES
+
+* start(): no longer resolves when the microphone stream fails. Callers who did not handle rejections will receive an UnhandledPromiseRejection.
+Migration: wrap await vocal.start() in try/catch, or use .catch().
+
+# [2.0.0-beta.3](https://github.com/untemps/vocal/compare/v2.0.0-beta.2...v2.0.0-beta.3) (2026-05-15)
+
+
+### Features
+
+* Expose AbortSignal support in start() ([#42](https://github.com/untemps/vocal/issues/42)) ([a7f638b](https://github.com/untemps/vocal/commit/a7f638b541347a4377bce1f43a47aa5290ea2852))
+
 # [2.0.0-beta.2](https://github.com/untemps/vocal/compare/v2.0.0-beta.1...v2.0.0-beta.2) (2026-05-15)
 
 

package/README.md

@@ -33,11 +33,15 @@ const vocal = new Vocal(options)
 // Subscribe to Vocal instance events (see below for all available events)
 vocal.addEventListener('speechstart', (event) => console.log('Vocal starts recording'))
 vocal.addEventListener('speechend', (event) => console.log('Vocal stops recording'))
-vocal.addEventListener('result', (event, transcript, alternatives) => console.log('Vocal catches a result:', transcript, alternatives))
-vocal.addEventListener('error', (error) => { throw error })
-
-// Start recording
-vocal.start()
+vocal.addEventListener('result', (event, bestAlternative, alternatives) => console.log('Vocal catches a result:', bestAlternative, alternatives))
+vocal.addEventListener('error', (event) => console.error(event.error, event.message))
+
+// Start recording — rejects on error
+try {
+  await vocal.start()
+} catch (error) {
+  // handle error
+}
 
 // Stop/Pause recording
 vocal.stop()
@@ -58,9 +62,22 @@ Please refer to [this section](https://developer.mozilla.org/en-US/docs/Web/API/
 | ---------------- | ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------- |
 | grammars         | SpeechGrammarList | null       | Grammars understood by the recognition [JSpeech Grammar Format](https://www.w3.org/TR/jsgf/)                      |
 | lang             | string            | 'en-US'    | Language understood by the recognition [BCP 47 language tag](https://tools.ietf.org/html/bcp47)                   |
-| continuous       | boolean           | false      | Whether continuous results are returned for each recognition, or only a single result                             |
+| continuous       | boolean           | false      | Whether continuous results are returned for each recognition, or only a single result (see [Continuous mode](#continuous-mode)) |
 | interimResults   | boolean           | false      | Whether interim results should be returned or not. Interim results are results that are not yet final             |
 | maxAlternatives  | number            | 1          | Maximum number of SpeechRecognitionAlternatives provided per result                                               |
+
+### Continuous mode
+
+Browsers (notably Chrome) automatically end a recognition session after a few seconds of silence, even when `continuous` is `true`. Vocal transparently restarts the underlying engine after such a silence-induced `end`, so recording keeps running until `stop()` or `abort()` is explicitly called. The intermediate `end` and `start` events triggered by the restart are not forwarded to user listeners — `isRecording` stays `true` across the restart, and the cycle is throttled to at most one restart per second to avoid `InvalidStateError`.
+
+The restart is disabled automatically when the recognition emits a fatal error (`not-allowed`, `service-not-allowed`, `audio-capture`).
+
+#### Aggregated result on stop
+
+To compensate for results being split across silent restart cycles, Vocal accumulates every final result (`isFinal: true`) received during a session. On explicit `stop()`, an extra `result` event is emitted just before `end`, carrying the joined transcripts as a single string. Interim results and `abort()` are excluded — `abort()` discards the buffer without emitting.
+
+The aggregated event is a synthetic `Event` shaped to match `SpeechRecognitionEvent` (`resultIndex` + `results[0][0].transcript`); it is not a real `SpeechRecognitionEvent` instance, so `event instanceof SpeechRecognitionEvent` returns `false`. Read the transcript through the second argument of the listener (`bestAlternative`).
+
 ## Events
 
 Events described below are those from the `SpeechRecognition` Web API.  
@@ -73,7 +90,7 @@ Please refer to [this section](https://developer.mozilla.org/en-US/docs/Web/API/
 | end         | Fired when the recognition service has disconnected                                       |
 | error       | Fired when a recognition error occurs                                                     |
 | nomatch     | Fired when the recognition service returns a final result with no significant recognition |
-| result      | Fired when the recognition service returns a result — callback receives `(event, transcript: string, alternatives: string[])` where `transcript === alternatives[0]` |
+| result      | Fired when the recognition service returns a result — callback receives `(event, bestAlternative: string, alternatives: string[])` where `bestAlternative` is the alternative with the highest confidence |
 | soundend    | Fired when any sound — recognisable or not — has stopped being detected                   |
 | soundstart  | Fired when any sound — recognisable or not — has been detected                            |
 | speechend   | Fired when speech recognized by the recognition service has stopped being detected        |
@@ -85,5 +102,71 @@ Please refer to [this section](https://developer.mozilla.org/en-US/docs/Web/API/
 | Getter      | Type                      | Description                                                                                                          |
 | ----------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | isSupported | boolean                   | Whether the current environment supports the SpeechRecognition Web API (static)                                      |
-| instance    | SpeechRecognition \| null | The underlying SpeechRecognition instance                                                                            |
 | isRecording | boolean                   | Whether recognition is currently active — `true` after `start()`, `false` after `stop()`, `abort()`, or `end` event |
+
+## Methods
+
+### `start({ signal? })`
+
+| Parameter | Type          | Default     | Description                                                                   |
+| --------- | ------------- | ----------- | ----------------------------------------------------------------------------- |
+| signal    | AbortSignal   | `undefined` | Cancels the in-flight microphone permission request when the signal is aborted |
+
+```js
+const controller = new AbortController()
+vocal.start({ signal: controller.signal })
+
+// Cancel the permission request at any later point
+controller.abort()
+```
+
+### `stop()`
+
+Stops recognition gracefully, allowing the current audio to be processed before disconnecting. Sets `isRecording` to `false`.
+
+### `abort()`
+
+Stops recognition immediately without processing pending audio. Sets `isRecording` to `false`.
+
+### `addEventListener(eventType, callback)`
+
+Registers a callback for the given event type. Multiple callbacks can be registered for the same type — they stack and all fire in registration order.
+
+| Parameter | Type                                              | Description                                |
+| --------- | ------------------------------------------------- | ------------------------------------------ |
+| eventType | `EventType`                                       | One of the valid event type strings        |
+| callback  | `ResultEventHandler \| ErrorEventHandler \| GenericEventHandler` | Callback invoked when the event fires |
+
+Throws if `eventType` is not a valid `EventType`.
+
+### `removeEventListener(eventType, callback?)`
+
+Removes a listener for the given event type.
+
+| Parameter | Type                                              | Default     | Description                                          |
+| --------- | ------------------------------------------------- | ----------- | ---------------------------------------------------- |
+| eventType | `EventType`                                       |             | One of the valid event type strings                  |
+| callback  | `ResultEventHandler \| ErrorEventHandler \| GenericEventHandler` | `undefined` | Specific callback to remove. Omit to remove all listeners for this type |
+
+Throws if `eventType` is not a valid `EventType`.
+
+### `once(eventType, callback)`
+
+Registers a one-shot listener that automatically unregisters itself after firing once.
+
+| Parameter | Type                                              | Description                                |
+| --------- | ------------------------------------------------- | ------------------------------------------ |
+| eventType | `EventType`                                       | One of the valid event type strings        |
+| callback  | `ResultEventHandler \| ErrorEventHandler \| GenericEventHandler` | Callback invoked once when the event fires |
+
+```js
+vocal.once('result', (event, bestAlternative, alternatives) => {
+    console.log(bestAlternative)
+    vocal.stop()
+})
+```
+
+### `cleanup()`
+
+Stops recognition, removes all registered listeners, and releases the internal `SpeechRecognition` instance. The `Vocal` object cannot be reused after `cleanup()`.
+

package/dist/index.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@untemps/user-permissions-utils`);var t=1e3,n=new Set([`not-allowed`,`service-not-allowed`,`audio-capture`]),r=class r{static defaultOptions={grammars:null,lang:`en-US`,continuous:!1,interimResults:!1,maxAlternatives:1};static eventTypes={AUDIO_END:`audioend`,AUDIO_START:`audiostart`,END:`end`,ERROR:`error`,NO_MATCH:`nomatch`,RESULT:`result`,SOUND_END:`soundend`,SOUND_START:`soundstart`,SPEECH_END:`speechend`,SPEECH_START:`speechstart`,START:`start`};static get isSupported(){return!!r._resolveSpeechRecognition()&&!!(0,e.isNavigatorPermissionsSupported)()&&!!(0,e.isNavigatorMediaDevicesSupported)()}static set isSupported(e){throw Error(`You cannot set isSupported directly.`)}_instance=null;_listeners={};_isRecording=!1;_explicitStop=!1;_lastStartedAt=0;_restartTimeoutId=null;_isRestarting=!1;_finalTranscripts=[];_onEnd=e=>{if(this._shouldAutoRestart()){let n=Math.max(0,t-(Date.now()-this._lastStartedAt));this._isRestarting=!0,this._restartTimeoutId=setTimeout(()=>this._restart(),n),e.stopImmediatePropagation();return}this._isRecording=!1};_onStart=e=>{this._isRestarting&&(e.stopImmediatePropagation(),queueMicrotask(()=>{this._isRestarting=!1}))};_onError=e=>{n.has(e.error)&&(this._explicitStop=!0,this._clearRestartTimeout(),this._isRecording=!1)};_onResult=e=>{let t=e,n=t.results?.[t.resultIndex];n?.isFinal&&this._finalTranscripts.push(r._pickBestAlternative(Array.from(n)).transcript)};constructor(e){let t=r._resolveSpeechRecognition();if(!t)throw new DOMException(`SpeechRecognition not supported`,`NOT_SUPPORTED_ERR`);this._instance=new t;let{grammars:n,...i}={...r.defaultOptions,...e??{}},a=this._instance;if(Object.assign(a,i),n)a.grammars=n;else{let e=r._resolveSpeechGrammarList();a.grammars=e?new e:null}this._instance.addEventListener(r.eventTypes.END,this._onEnd),this._instance.addEventListener(r.eventTypes.START,this._onStart),this._instance.addEventListener(r.eventTypes.ERROR,this._onError),this._instance.addEventListener(r.eventTypes.RESULT,this._onResult)}get isRecording(){return this._isRecording}set isRecording(e){throw Error(`You cannot set isRecording directly.`)}async start({signal:t}={}){if(this._instance)try{if(!await(0,e.getUserMediaStream)(`microphone`,{audio:!0},{signal:t}))throw Error(`Unable to retrieve the stream from media device`);this._explicitStop=!1,this._finalTranscripts=[],this._instance.start(),this._isRecording=!0,this._lastStartedAt=Date.now()}catch(e){if(e instanceof Error&&e.name===`AbortError`)return this;throw e}return this}stop(){return this._instance&&(this._explicitStop=!0,this._clearRestartTimeout(),this._emitAggregatedResult(),this._instance.stop(),this._isRecording=!1),this}abort(){return this._instance&&(this._explicitStop=!0,this._clearRestartTimeout(),this._instance.abort(),this._isRecording=!1,this._finalTranscripts=[]),this}addEventListener(e,t){if(!this._includesEventType(e))throw Error(this._unknownEventTypeMessage(e));if(this._instance){let n=n=>{if(this._isRestarting&&(e===r.eventTypes.END||e===r.eventTypes.START))return;let i=[];if(e===r.eventTypes.RESULT){let e=n;if(e.results?.length>0&&e.resultIndex<e.results.length){let t=Array.from(e.results[e.resultIndex]);i.push(r._pickBestAlternative(t).transcript,t.map(e=>e.transcript))}}t.call(this,n,...i)};this._instance.addEventListener(e,n),this._listeners[e]||(this._listeners[e]=[]),this._listeners[e].push({callback:t,handler:n})}return this}removeEventListener(e,t){if(!this._includesEventType(e))throw Error(this._unknownEventTypeMessage(e));let n=this._instance;if(n&&this._listeners[e])if(t!==void 0){let r=this._listeners[e].findIndex(e=>e.callback===t);r!==-1&&(n.removeEventListener(e,this._listeners[e][r].handler),this._listeners[e].splice(r,1),this._listeners[e].length===0&&delete this._listeners[e])}else this._listeners[e].forEach(({handler:t})=>n.removeEventListener(e,t)),delete this._listeners[e];return this}once(e,t){let n=(...r)=>{t.call(this,...r),this.removeEventListener(e,n)};return this.addEventListener(e,n)}cleanup(){return this.stop(),Object.keys(this._listeners).forEach(e=>this.removeEventListener(e)),this._instance?.removeEventListener(r.eventTypes.END,this._onEnd),this._instance?.removeEventListener(r.eventTypes.START,this._onStart),this._instance?.removeEventListener(r.eventTypes.ERROR,this._onError),this._instance?.removeEventListener(r.eventTypes.RESULT,this._onResult),this._instance=null,this}_restart=()=>{this._restartTimeoutId=null;try{this._instance.start(),this._lastStartedAt=Date.now()}catch{this._isRestarting=!1,this._isRecording=!1}};_emitAggregatedResult(){let e=this._finalTranscripts;if(this._finalTranscripts=[],e.length===0)return;let t=e.join(` `).trim(),n=Object.assign([{transcript:t,confidence:1}],{isFinal:!0}),i=Object.assign(new Event(r.eventTypes.RESULT),{resultIndex:0,results:[n]});[...this._listeners[r.eventTypes.RESULT]??[]].forEach(({handler:e})=>e(i))}static _pickBestAlternative(e){return e.reduce((e,t)=>(t.confidence??0)>(e.confidence??0)?t:e)}_shouldAutoRestart(){return!!this._instance&&!this._explicitStop&&this._instance.continuous}_clearRestartTimeout(){this._restartTimeoutId!==null&&(clearTimeout(this._restartTimeoutId),this._restartTimeoutId=null),this._isRestarting=!1}_includesEventType(e){return Object.values(r.eventTypes).includes(e)}_unknownEventTypeMessage(e){return`Unknown event type "${e}". Valid types are: ${Object.values(r.eventTypes).join(`, `)}.`}static _resolveSpeechRecognition(){if(!(typeof window>`u`))return window.SpeechRecognition??window.webkitSpeechRecognition??window.mozSpeechRecognition??window.msSpeechRecognition}static _resolveSpeechGrammarList(){return window.SpeechGrammarList??window.webkitSpeechGrammarList??window.mozSpeechGrammarList??window.msSpeechGrammarList}};exports.Vocal=r;
+//# sourceMappingURL=index.cjs.map

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { default as Vocal } from './Vocal';
-export type { VocalOptions, EventType } from './Vocal';
+export type { VocalOptions, EventType, ResultEventHandler, ErrorEventHandler, GenericEventHandler, EventHandlerFor, } from './Vocal';

package/dist/index.es.js

@@ -1,6 +1,10 @@
 import { getUserMediaStream as e, isNavigatorMediaDevicesSupported as t, isNavigatorPermissionsSupported as n } from "@untemps/user-permissions-utils";
 //#region src/Vocal.ts
-var r = class r {
+var r = 1e3, i = new Set([
+	"not-allowed",
+	"service-not-allowed",
+	"audio-capture"
+]), a = class a {
 	static defaultOptions = {
 		grammars: null,
 		lang: "en-US",
@@ -22,36 +26,53 @@ var r = class r {
 		START: "start"
 	};
 	static get isSupported() {
-		return !!r._resolveSpeechRecognition() && !!n() && !!t();
+		return !!a._resolveSpeechRecognition() && !!n() && !!t();
 	}
 	static set isSupported(e) {
 		throw Error("You cannot set isSupported directly.");
 	}
 	_instance = null;
-	_listeners = null;
+	_listeners = {};
 	_isRecording = !1;
+	_explicitStop = !1;
+	_lastStartedAt = 0;
+	_restartTimeoutId = null;
+	_isRestarting = !1;
+	_finalTranscripts = [];
+	_onEnd = (e) => {
+		if (this._shouldAutoRestart()) {
+			let t = Math.max(0, r - (Date.now() - this._lastStartedAt));
+			this._isRestarting = !0, this._restartTimeoutId = setTimeout(() => this._restart(), t), e.stopImmediatePropagation();
+			return;
+		}
+		this._isRecording = !1;
+	};
+	_onStart = (e) => {
+		this._isRestarting && (e.stopImmediatePropagation(), queueMicrotask(() => {
+			this._isRestarting = !1;
+		}));
+	};
+	_onError = (e) => {
+		i.has(e.error) && (this._explicitStop = !0, this._clearRestartTimeout(), this._isRecording = !1);
+	};
+	_onResult = (e) => {
+		let t = e, n = t.results?.[t.resultIndex];
+		n?.isFinal && this._finalTranscripts.push(a._pickBestAlternative(Array.from(n)).transcript);
+	};
 	constructor(e) {
-		let t = r._resolveSpeechRecognition();
+		let t = a._resolveSpeechRecognition();
 		if (!t) throw new DOMException("SpeechRecognition not supported", "NOT_SUPPORTED_ERR");
-		this._instance = new t(), this._listeners = {};
-		let { grammars: n, ...i } = {
-			...r.defaultOptions,
+		this._instance = new t();
+		let { grammars: n, ...r } = {
+			...a.defaultOptions,
 			...e ?? {}
-		}, a = this._instance;
-		if (Object.assign(a, i), n) a.grammars = n;
+		}, i = this._instance;
+		if (Object.assign(i, r), n) i.grammars = n;
 		else {
-			let e = r._resolveSpeechGrammarList();
-			a.grammars = e ? new e() : null;
+			let e = a._resolveSpeechGrammarList();
+			i.grammars = e ? new e() : null;
 		}
-		this._instance.addEventListener("end", () => {
-			this._isRecording = !1;
-		});
-	}
-	get instance() {
-		return this._instance;
-	}
-	set instance(e) {
-		throw Error("You cannot set instance directly.");
+		this._instance.addEventListener(a.eventTypes.END, this._onEnd), this._instance.addEventListener(a.eventTypes.START, this._onStart), this._instance.addEventListener(a.eventTypes.ERROR, this._onError), this._instance.addEventListener(a.eventTypes.RESULT, this._onResult);
 	}
 	get isRecording() {
 		return this._isRecording;
@@ -59,61 +80,105 @@ var r = class r {
 	set isRecording(e) {
 		throw Error("You cannot set isRecording directly.");
 	}
-	async start() {
+	async start({ signal: t } = {}) {
 		if (this._instance) try {
-			if (!await e("microphone", { audio: !0 })) throw Error("Unable to retrieve the stream from media device");
-			this._instance.start(), this._isRecording = !0;
+			if (!await e("microphone", { audio: !0 }, { signal: t })) throw Error("Unable to retrieve the stream from media device");
+			this._explicitStop = !1, this._finalTranscripts = [], this._instance.start(), this._isRecording = !0, this._lastStartedAt = Date.now();
 		} catch (e) {
-			let t = this._listeners?.error;
-			t && t(e);
+			if (e instanceof Error && e.name === "AbortError") return this;
+			throw e;
 		}
 		return this;
 	}
 	stop() {
-		return this._instance && (this._instance.stop(), this._isRecording = !1), this;
+		return this._instance && (this._explicitStop = !0, this._clearRestartTimeout(), this._emitAggregatedResult(), this._instance.stop(), this._isRecording = !1), this;
 	}
 	abort() {
-		return this._instance && (this._instance.abort(), this._isRecording = !1), this;
+		return this._instance && (this._explicitStop = !0, this._clearRestartTimeout(), this._instance.abort(), this._isRecording = !1, this._finalTranscripts = []), this;
 	}
 	addEventListener(e, t) {
-		if (this._instance && this._listeners && this._includesEventType(e)) {
-			this._listeners[e] && this.removeEventListener(e);
+		if (!this._includesEventType(e)) throw Error(this._unknownEventTypeMessage(e));
+		if (this._instance) {
 			let n = (n) => {
-				let i = [];
-				if (e === r.eventTypes.RESULT) {
+				if (this._isRestarting && (e === a.eventTypes.END || e === a.eventTypes.START)) return;
+				let r = [];
+				if (e === a.eventTypes.RESULT) {
 					let e = n;
-					if (e.results?.length > 0) {
-						let t = Array.from(e.results[0], (e) => e.transcript);
-						i.push(t[0], t);
+					if (e.results?.length > 0 && e.resultIndex < e.results.length) {
+						let t = Array.from(e.results[e.resultIndex]);
+						r.push(a._pickBestAlternative(t).transcript, t.map((e) => e.transcript));
 					}
 				}
-				t.apply(this, [n, ...i]);
+				t.call(this, n, ...r);
 			};
-			this._instance.addEventListener(e, n), this._listeners[e] = n;
+			this._instance.addEventListener(e, n), this._listeners[e] || (this._listeners[e] = []), this._listeners[e].push({
+				callback: t,
+				handler: n
+			});
 		}
 		return this;
 	}
-	removeEventListener(e) {
-		if (this._instance && this._listeners) {
-			let t = this._listeners[e];
-			this._instance.removeEventListener(e, t), delete this._listeners[e];
-		}
+	removeEventListener(e, t) {
+		if (!this._includesEventType(e)) throw Error(this._unknownEventTypeMessage(e));
+		let n = this._instance;
+		if (n && this._listeners[e]) if (t !== void 0) {
+			let r = this._listeners[e].findIndex((e) => e.callback === t);
+			r !== -1 && (n.removeEventListener(e, this._listeners[e][r].handler), this._listeners[e].splice(r, 1), this._listeners[e].length === 0 && delete this._listeners[e]);
+		} else this._listeners[e].forEach(({ handler: t }) => n.removeEventListener(e, t)), delete this._listeners[e];
 		return this;
 	}
+	once(e, t) {
+		let n = (...r) => {
+			t.call(this, ...r), this.removeEventListener(e, n);
+		};
+		return this.addEventListener(e, n);
+	}
 	cleanup() {
-		return this.stop(), Object.keys(this._listeners).forEach((e) => this.removeEventListener(e)), this._instance = null, this;
+		return this.stop(), Object.keys(this._listeners).forEach((e) => this.removeEventListener(e)), this._instance?.removeEventListener(a.eventTypes.END, this._onEnd), this._instance?.removeEventListener(a.eventTypes.START, this._onStart), this._instance?.removeEventListener(a.eventTypes.ERROR, this._onError), this._instance?.removeEventListener(a.eventTypes.RESULT, this._onResult), this._instance = null, this;
+	}
+	_restart = () => {
+		this._restartTimeoutId = null;
+		try {
+			this._instance.start(), this._lastStartedAt = Date.now();
+		} catch {
+			this._isRestarting = !1, this._isRecording = !1;
+		}
+	};
+	_emitAggregatedResult() {
+		let e = this._finalTranscripts;
+		if (this._finalTranscripts = [], e.length === 0) return;
+		let t = e.join(" ").trim(), n = Object.assign([{
+			transcript: t,
+			confidence: 1
+		}], { isFinal: !0 }), r = Object.assign(new Event(a.eventTypes.RESULT), {
+			resultIndex: 0,
+			results: [n]
+		});
+		[...this._listeners[a.eventTypes.RESULT] ?? []].forEach(({ handler: e }) => e(r));
+	}
+	static _pickBestAlternative(e) {
+		return e.reduce((e, t) => (t.confidence ?? 0) > (e.confidence ?? 0) ? t : e);
+	}
+	_shouldAutoRestart() {
+		return !!this._instance && !this._explicitStop && this._instance.continuous;
+	}
+	_clearRestartTimeout() {
+		this._restartTimeoutId !== null && (clearTimeout(this._restartTimeoutId), this._restartTimeoutId = null), this._isRestarting = !1;
 	}
 	_includesEventType(e) {
-		return Object.values(r.eventTypes).includes(e);
+		return Object.values(a.eventTypes).includes(e);
+	}
+	_unknownEventTypeMessage(e) {
+		return `Unknown event type "${e}". Valid types are: ${Object.values(a.eventTypes).join(", ")}.`;
 	}
 	static _resolveSpeechRecognition() {
-		return window.SpeechRecognition ?? window.webkitSpeechRecognition ?? window.mozSpeechRecognition ?? window.msSpeechRecognition;
+		if (!(typeof window > "u")) return window.SpeechRecognition ?? window.webkitSpeechRecognition ?? window.mozSpeechRecognition ?? window.msSpeechRecognition;
 	}
 	static _resolveSpeechGrammarList() {
 		return window.SpeechGrammarList ?? window.webkitSpeechGrammarList ?? window.mozSpeechGrammarList ?? window.msSpeechGrammarList;
 	}
 };
 //#endregion
-export { r as Vocal };
+export { a as Vocal };
 
 //# sourceMappingURL=index.es.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@untemps/vocal",
-	"version": "2.0.0-beta.2",
+	"version": "2.0.0-beta.20",
 	"description": "Class wrapped around the SpeechRecognition Web API",
 	"repository": "git@github.com:untemps/vocal.git",
 	"keywords": [
@@ -13,6 +13,7 @@
 	"author": "Vincent Le Badezet <v.lebadezet@untemps.net>",
 	"license": "MIT",
 	"private": false,
+	"type": "module",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -20,20 +21,19 @@
 		"node": ">=22"
 	},
 	"files": [
-		"dist/index.js",
+		"dist/index.cjs",
 		"dist/index.es.js",
-		"dist/index.umd.js",
 		"dist/index.d.ts",
 		"CHANGELOG.md"
 	],
-	"main": "dist/index.js",
+	"main": "dist/index.cjs",
 	"module": "dist/index.es.js",
 	"types": "dist/index.d.ts",
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.es.js",
-			"require": "./dist/index.js",
+			"require": "./dist/index.cjs",
 			"default": "./dist/index.es.js"
 		}
 	},
@@ -60,7 +60,7 @@
 		"vitest": "^4.1.5"
 	},
 	"dependencies": {
-		"@untemps/user-permissions-utils": "^1.3.0"
+		"@untemps/user-permissions-utils": "^1.3.3"
 	},
 	"release": {
 		"branches": [
@@ -91,16 +91,12 @@
 				{
 					"assets": [
 						{
-							"path": "dist/index.js",
+							"path": "dist/index.cjs",
 							"label": "CJS distribution"
 						},
 						{
 							"path": "dist/index.es.js",
 							"label": "ES distribution"
-						},
-						{
-							"path": "dist/index.umd.js",
-							"label": "UMD distribution"
 						}
 					]
 				}
@@ -108,12 +104,13 @@
 		]
 	},
 	"scripts": {
+		"dev": "vite demo --config demo/vite.config.js",
 		"test": "vitest",
 		"test:ci": "vitest run --coverage",
 		"build": "vite build",
 		"typecheck": "tsc --noEmit",
 		"lint": "eslint src/ vitest.setup.ts",
 		"prepare": "husky",
-		"prettier": "prettier \"src/**/*.{ts,js}\" vitest.setup.ts --ignore-path ./.prettierignore --write"
+		"prettier": "prettier \"src/**/*.{ts,js}\" vitest.setup.ts \"*.{js,ts}\" --ignore-path ./.prettierignore --write"
 	}
 }

package/dist/index.js

@@ -1,2 +0,0 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@untemps/user-permissions-utils`);var t=class t{static defaultOptions={grammars:null,lang:`en-US`,continuous:!1,interimResults:!1,maxAlternatives:1};static eventTypes={AUDIO_END:`audioend`,AUDIO_START:`audiostart`,END:`end`,ERROR:`error`,NO_MATCH:`nomatch`,RESULT:`result`,SOUND_END:`soundend`,SOUND_START:`soundstart`,SPEECH_END:`speechend`,SPEECH_START:`speechstart`,START:`start`};static get isSupported(){return!!t._resolveSpeechRecognition()&&!!(0,e.isNavigatorPermissionsSupported)()&&!!(0,e.isNavigatorMediaDevicesSupported)()}static set isSupported(e){throw Error(`You cannot set isSupported directly.`)}_instance=null;_listeners=null;_isRecording=!1;constructor(e){let n=t._resolveSpeechRecognition();if(!n)throw new DOMException(`SpeechRecognition not supported`,`NOT_SUPPORTED_ERR`);this._instance=new n,this._listeners={};let{grammars:r,...i}={...t.defaultOptions,...e??{}},a=this._instance;if(Object.assign(a,i),r)a.grammars=r;else{let e=t._resolveSpeechGrammarList();a.grammars=e?new e:null}this._instance.addEventListener(`end`,()=>{this._isRecording=!1})}get instance(){return this._instance}set instance(e){throw Error(`You cannot set instance directly.`)}get isRecording(){return this._isRecording}set isRecording(e){throw Error(`You cannot set isRecording directly.`)}async start(){if(this._instance)try{if(!await(0,e.getUserMediaStream)(`microphone`,{audio:!0}))throw Error(`Unable to retrieve the stream from media device`);this._instance.start(),this._isRecording=!0}catch(e){let t=this._listeners?.error;t&&t(e)}return this}stop(){return this._instance&&(this._instance.stop(),this._isRecording=!1),this}abort(){return this._instance&&(this._instance.abort(),this._isRecording=!1),this}addEventListener(e,n){if(this._instance&&this._listeners&&this._includesEventType(e)){this._listeners[e]&&this.removeEventListener(e);let r=r=>{let i=[];if(e===t.eventTypes.RESULT){let e=r;if(e.results?.length>0){let t=Array.from(e.results[0],e=>e.transcript);i.push(t[0],t)}}n.apply(this,[r,...i])};this._instance.addEventListener(e,r),this._listeners[e]=r}return this}removeEventListener(e){if(this._instance&&this._listeners){let t=this._listeners[e];this._instance.removeEventListener(e,t),delete this._listeners[e]}return this}cleanup(){return this.stop(),Object.keys(this._listeners).forEach(e=>this.removeEventListener(e)),this._instance=null,this}_includesEventType(e){return Object.values(t.eventTypes).includes(e)}static _resolveSpeechRecognition(){return window.SpeechRecognition??window.webkitSpeechRecognition??window.mozSpeechRecognition??window.msSpeechRecognition}static _resolveSpeechGrammarList(){return window.SpeechGrammarList??window.webkitSpeechGrammarList??window.mozSpeechGrammarList??window.msSpeechGrammarList}};exports.Vocal=t;
-//# sourceMappingURL=index.js.map

package/dist/index.umd.js

@@ -1,2 +0,0 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require(`@untemps/user-permissions-utils`)):typeof define==`function`&&define.amd?define([`exports`,`@untemps/user-permissions-utils`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.Vocal={},e.UserPermissionsUtils))})(this,function(e,t){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`}),e.Vocal=class e{static defaultOptions={grammars:null,lang:`en-US`,continuous:!1,interimResults:!1,maxAlternatives:1};static eventTypes={AUDIO_END:`audioend`,AUDIO_START:`audiostart`,END:`end`,ERROR:`error`,NO_MATCH:`nomatch`,RESULT:`result`,SOUND_END:`soundend`,SOUND_START:`soundstart`,SPEECH_END:`speechend`,SPEECH_START:`speechstart`,START:`start`};static get isSupported(){return!!e._resolveSpeechRecognition()&&!!(0,t.isNavigatorPermissionsSupported)()&&!!(0,t.isNavigatorMediaDevicesSupported)()}static set isSupported(e){throw Error(`You cannot set isSupported directly.`)}_instance=null;_listeners=null;_isRecording=!1;constructor(t){let n=e._resolveSpeechRecognition();if(!n)throw new DOMException(`SpeechRecognition not supported`,`NOT_SUPPORTED_ERR`);this._instance=new n,this._listeners={};let{grammars:r,...i}={...e.defaultOptions,...t??{}},a=this._instance;if(Object.assign(a,i),r)a.grammars=r;else{let t=e._resolveSpeechGrammarList();a.grammars=t?new t:null}this._instance.addEventListener(`end`,()=>{this._isRecording=!1})}get instance(){return this._instance}set instance(e){throw Error(`You cannot set instance directly.`)}get isRecording(){return this._isRecording}set isRecording(e){throw Error(`You cannot set isRecording directly.`)}async start(){if(this._instance)try{if(!await(0,t.getUserMediaStream)(`microphone`,{audio:!0}))throw Error(`Unable to retrieve the stream from media device`);this._instance.start(),this._isRecording=!0}catch(e){let t=this._listeners?.error;t&&t(e)}return this}stop(){return this._instance&&(this._instance.stop(),this._isRecording=!1),this}abort(){return this._instance&&(this._instance.abort(),this._isRecording=!1),this}addEventListener(t,n){if(this._instance&&this._listeners&&this._includesEventType(t)){this._listeners[t]&&this.removeEventListener(t);let r=r=>{let i=[];if(t===e.eventTypes.RESULT){let e=r;if(e.results?.length>0){let t=Array.from(e.results[0],e=>e.transcript);i.push(t[0],t)}}n.apply(this,[r,...i])};this._instance.addEventListener(t,r),this._listeners[t]=r}return this}removeEventListener(e){if(this._instance&&this._listeners){let t=this._listeners[e];this._instance.removeEventListener(e,t),delete this._listeners[e]}return this}cleanup(){return this.stop(),Object.keys(this._listeners).forEach(e=>this.removeEventListener(e)),this._instance=null,this}_includesEventType(t){return Object.values(e.eventTypes).includes(t)}static _resolveSpeechRecognition(){return window.SpeechRecognition??window.webkitSpeechRecognition??window.mozSpeechRecognition??window.msSpeechRecognition}static _resolveSpeechGrammarList(){return window.SpeechGrammarList??window.webkitSpeechGrammarList??window.mozSpeechGrammarList??window.msSpeechGrammarList}}});
-//# sourceMappingURL=index.umd.js.map