web-audio-recorder-ts 1.0.0 → 1.0.2

package/README.md

@@ -1,15 +1,22 @@
 # web-audio-recorder-ts
 
+[![npm version](https://img.shields.io/npm/v/web-audio-recorder-ts.svg)](https://www.npmjs.com/package/web-audio-recorder-ts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 TypeScript port of [web-audio-recorder-js](https://github.com/higuma/web-audio-recorder-js) with full type support for WAV, OGG Vorbis, and MP3 audio recording in browsers.
 
+**✨ No manual file copying required!** The library automatically detects and loads encoder files from the npm package.
+
 ## Features
 
-- ✅ Full TypeScript support with type definitions
-- ✅ Record audio in WAV, OGG Vorbis, and MP3 formats
-- ✅ Modern ES modules, CommonJS, and UMD builds
-- ✅ Zero runtime dependencies
-- ✅ Works in browsers and Web Workers
-- ✅ Type-safe API with IntelliSense support
+- ✅ **Full TypeScript support** with complete type definitions
+- ✅ **Record audio in WAV, OGG Vorbis, and MP3 formats**
+- ✅ **Automatic encoder file detection** - no manual file copying needed!
+- ✅ **Modern build system** - ES modules, CommonJS, and UMD outputs
+- ✅ **Zero runtime dependencies** - pure TypeScript/JavaScript
+- ✅ **Works in browsers and Web Workers**
+- ✅ **Type-safe API** with full IntelliSense support
+- ✅ **Production ready** - tested and published on npm
 
 ## Installation
 
@@ -60,15 +67,8 @@ const blob = await recorder.stop();
 ```typescript
 import { WebAudioRecorderOgg, loadOggVorbisEncoder } from 'web-audio-recorder-ts';
 
-// Load encoder script first
-await loadOggVorbisEncoder('/path/to/OggVorbisEncoder.min.js');
-
-// Configure memory initializer path (if needed)
-if (typeof window !== 'undefined') {
-  (window as any).OggVorbisEncoderConfig = {
-    memoryInitializerPrefixURL: '/path/to/'
-  };
-}
+// Load encoder script (auto-detects from node_modules - no path needed!)
+await loadOggVorbisEncoder();
 
 const audioContext = new AudioContext();
 const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
@@ -79,6 +79,10 @@ const recorder = new WebAudioRecorderOgg(
   { quality: 0.7 } // OGG quality: -0.1 to 1.0
 );
 
+recorder.setOnComplete((event) => {
+  console.log('OGG recording complete!', event.url);
+});
+
 await recorder.start(stream);
 const blob = await recorder.stop();
 ```
@@ -88,15 +92,8 @@ const blob = await recorder.stop();
 ```typescript
 import { WebAudioRecorderMp3, loadMp3LameEncoder } from 'web-audio-recorder-ts';
 
-// Load encoder script first
-await loadMp3LameEncoder('/path/to/Mp3LameEncoder.min.js');
-
-// Configure memory initializer path (if needed)
-if (typeof window !== 'undefined') {
-  (window as any).Mp3LameEncoderConfig = {
-    memoryInitializerPrefixURL: '/path/to/'
-  };
-}
+// Load encoder script (auto-detects from node_modules - no path needed!)
+await loadMp3LameEncoder();
 
 const audioContext = new AudioContext();
 const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
@@ -107,6 +104,10 @@ const recorder = new WebAudioRecorderMp3(
   { bitrate: 192 } // MP3 bitrate in kbps
 );
 
+recorder.setOnComplete((event) => {
+  console.log('MP3 recording complete!', event.url);
+});
+
 await recorder.start(stream);
 const blob = await recorder.stop();
 ```
@@ -194,15 +195,29 @@ enum RecorderStatus {
 
 ## Setup for OGG and MP3
 
-OGG and MP3 encoders require external JavaScript files compiled via Emscripten. You need to:
+OGG and MP3 encoders require external JavaScript files compiled via Emscripten. The good news is that **you don't need to copy any files manually** - the library will automatically detect and load them from the npm package!
+
+### Automatic Loading (Recommended)
+
+Simply call the loader functions without any parameters, and the library will automatically find the encoder files:
+
+```typescript
+// For OGG - automatically finds the file in node_modules
+await loadOggVorbisEncoder();
+
+// For MP3 - automatically finds the file in node_modules
+await loadMp3LameEncoder();
+```
+
+The library will:
 
-1. Copy the encoder files to your project:
-   - `OggVorbisEncoder.min.js` and `OggVorbisEncoder.min.js.mem`
-   - `Mp3LameEncoder.min.js` and `Mp3LameEncoder.min.js.mem`
+1. Automatically detect the package location in `node_modules`
+2. Configure the memory initializer paths for `.mem` files
+3. Load the encoder scripts from the correct location
 
-2. These files are included in the `lib/` directory of this package.
+### Manual Path (If Needed)
 
-3. Load the encoder scripts before creating recorders:
+If automatic detection fails (e.g., custom build setup), you can still provide the path manually:
 
 ```typescript
 // For OGG
@@ -212,26 +227,110 @@ await loadOggVorbisEncoder('/path/to/OggVorbisEncoder.min.js');
 await loadMp3LameEncoder('/path/to/Mp3LameEncoder.min.js');
 ```
 
-4. Configure memory initializer path if needed:
+### Advanced Configuration
+
+If you need more control, you can use the utility functions:
 
 ```typescript
-// For OGG
-window.OggVorbisEncoderConfig = {
-  memoryInitializerPrefixURL: '/path/to/'
-};
+import { 
+  configureEncoderPaths, 
+  getEncoderBaseUrl,
+  findEncoderPath 
+} from 'web-audio-recorder-ts';
 
-// For MP3
-window.Mp3LameEncoderConfig = {
-  memoryInitializerPrefixURL: '/path/to/'
-};
+// Configure paths manually
+configureEncoderPaths('/custom/path/to/lib');
+
+// Get the detected base URL
+const baseUrl = getEncoderBaseUrl();
+
+// Find encoder file path
+const oggPath = await findEncoderPath('OggVorbisEncoder.min.js');
+```
+
+### File Locations
+
+The encoder files are included in the `lib/` directory of the npm package:
+
+- `OggVorbisEncoder.min.js` and `OggVorbisEncoder.min.js.mem`
+- `Mp3LameEncoder.min.js` and `Mp3LameEncoder.min.js.mem`
+
+When installed via npm, they will be at:
+
+- `node_modules/web-audio-recorder-ts/lib/`
+
+## Framework Support
+
+### Nuxt.js
+
+If you're using Nuxt and seeing errors about TypeScript source files, see [NUXT_USAGE.md](./NUXT_USAGE.md) for detailed instructions.
+
+Quick fix - add to `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  vite: {
+    optimizeDeps: {
+      exclude: ['web-audio-recorder-ts']
+    }
+  }
+})
 ```
 
+### Vite / Vue
+
+Works out of the box! Just import and use.
+
+### Next.js
+
+Should work with default configuration. For OGG/MP3, ensure encoder files are accessible.
+
 ## Browser Support
 
-- Chrome/Edge: Full support
-- Firefox: Full support
-- Safari: Full support (may require user gesture for audio context)
-- Opera: Full support
+- ✅ Chrome/Edge: Full support
+- ✅ Firefox: Full support
+- ✅ Safari: Full support (may require user gesture for audio context)
+- ✅ Opera: Full support
+
+### Requirements
+
+- Modern browser with Web Audio API support
+- `getUserMedia` API for microphone access
+- For OGG/MP3: Server must be able to serve files from `node_modules` (or use manual paths)
+
+## Troubleshooting
+
+### Encoder files not found
+
+If automatic detection fails, you can:
+
+1. **Check if files exist**: Verify that `node_modules/web-audio-recorder-ts/lib/` contains the encoder files
+2. **Use manual paths**: Provide the path explicitly:
+
+   ```typescript
+   await loadOggVorbisEncoder('/path/to/OggVorbisEncoder.min.js');
+   ```
+
+3. **Check server configuration**: Ensure your dev server can serve files from `node_modules` (Vite, Webpack, etc.)
+
+### Memory initializer errors
+
+If you see errors about `.mem` files:
+
+1. The library automatically configures paths, but if needed:
+
+   ```typescript
+   import { configureEncoderPaths } from 'web-audio-recorder-ts';
+   configureEncoderPaths('/path/to/lib/');
+   ```
+
+### CORS errors
+
+If you see CORS errors when loading encoder files:
+
+- Ensure your server allows loading from `node_modules`
+- Consider copying files to `public/` folder in development
+- Use a CDN or absolute URLs in production
 
 ## License
 
@@ -244,18 +343,111 @@ See LICENSE file for details.
 ## Credits
 
 This is a TypeScript port of:
+
 - [web-audio-recorder-js](https://github.com/higuma/web-audio-recorder-js) by higuma
 - [ogg-vorbis-encoder-js](https://github.com/higuma/ogg-vorbis-encoder-js) by higuma
 
+## Development
+
+### Building
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the library
+pnpm build
+
+# Watch mode for development
+pnpm dev
+
+# Run demo
+pnpm demo
+```
+
+### Project Structure
+
+```
+web-audio-recorder-ts/
+├── src/
+│   ├── core/           # Core recorder classes and types
+│   ├── encoders/       # Audio encoders (WAV, OGG, MP3)
+│   ├── recorders/      # Format-specific recorders
+│   └── utils/          # Utility functions (auto-detection, etc.)
+├── lib/                # Emscripten encoder files
+├── types/              # TypeScript declarations for Emscripten
+├── demo/               # Demo application
+└── dist/               # Build output
+```
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Examples
+
+### Complete Example with Error Handling
+
+```typescript
+import { WebAudioRecorderWav } from 'web-audio-recorder-ts';
+
+async function recordAudio() {
+  try {
+    const audioContext = new AudioContext();
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    
+    const recorder = new WebAudioRecorderWav(audioContext, {
+      onDataAvailable: (event) => {
+        console.log('Data available:', event.data.length, 'bytes');
+      },
+      onComplete: (event) => {
+        console.log('Recording complete!');
+        // Download the file
+        const a = document.createElement('a');
+        a.href = event.url;
+        a.download = 'recording.wav';
+        a.click();
+      },
+      onError: (event) => {
+        console.error('Recording error:', event.message);
+      }
+    });
+    
+    await recorder.start(stream);
+    
+    // Record for 5 seconds
+    setTimeout(async () => {
+      const blob = await recorder.stop();
+      console.log('Blob size:', blob.size, 'bytes');
+      recorder.cleanup();
+    }, 5000);
+    
+  } catch (error) {
+    console.error('Failed to start recording:', error);
+  }
+}
+```
+
+## Repository
+
+- **GitHub**: [https://github.com/lucasbrito-wdt/web-audio-recorder](https://github.com/lucasbrito-wdt/web-audio-recorder)
+- **npm**: [https://www.npmjs.com/package/web-audio-recorder-ts](https://www.npmjs.com/package/web-audio-recorder-ts)
+- **Issues**: [https://github.com/lucasbrito-wdt/web-audio-recorder/issues](https://github.com/lucasbrito-wdt/web-audio-recorder/issues)
+
 ## Changelog
 
-### 1.0.0
+### 1.0.0 (2026-01-06)
 
-- Initial TypeScript port
-- Full type definitions
-- Support for WAV, OGG, and MP3 formats
-- Modern build system with ESM, CJS, and UMD outputs
+- ✨ **Initial TypeScript port** - Complete conversion from JavaScript
+- ✨ **Automatic encoder file detection** - No manual file copying required
+- ✨ **Full type definitions** - Complete TypeScript support with IntelliSense
+- ✨ **Support for WAV, OGG, and MP3 formats** - All three formats working
+- ✨ **Modern build system** - ESM, CJS, and UMD outputs
+- ✨ **Zero configuration** - Works out of the box with auto-detection
+- 📦 **Published on npm** - Ready for production use

package/dist/core/WebAudioRecorder.d.ts

@@ -82,4 +82,3 @@ export declare class WebAudioRecorder {
      */
     cleanup(): void;
 }
-//# sourceMappingURL=WebAudioRecorder.d.ts.map

package/dist/core/types.d.ts

@@ -106,4 +106,3 @@ export type CompleteCallback = (event: CompleteEvent) => void;
  * Callback para eventos de erro
  */
 export type ErrorCallback = (event: ErrorEvent) => void;
-//# sourceMappingURL=types.d.ts.map

package/dist/encoders/Mp3LameEncoder.d.ts

@@ -41,8 +41,7 @@ export declare class Mp3LameEncoderWrapper implements AudioEncoder {
 /**
  * Função helper para carregar o script Mp3LameEncoder
  *
- * @param scriptUrl - URL do script Mp3LameEncoder.min.js
+ * @param scriptUrl - URL do script Mp3LameEncoder.min.js (opcional, tenta auto-detectar se não fornecido)
  * @returns Promise que resolve quando o script é carregado
  */
-export declare function loadMp3LameEncoder(scriptUrl: string): Promise<void>;
-//# sourceMappingURL=Mp3LameEncoder.d.ts.map
+export declare function loadMp3LameEncoder(scriptUrl?: string): Promise<void>;

package/dist/encoders/Mp3LameEncoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Mp3LameEncoder.d.ts","sourceRoot":"","sources":["../../src/encoders/Mp3LameEncoder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAczD;;GAEG;AACH,qBAAa,qBAAsB,YAAW,YAAY;IACxD,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;OAMG;gBACS,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe;IAc7E;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI;IAYrC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,GAAE,MAAqB,GAAG,IAAI;IAQ7C;;OAEG;IACH,MAAM,IAAI,IAAI;CAMf;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqEnE"}
+{"version":3,"file":"Mp3LameEncoder.d.ts","sourceRoot":"","sources":["../../src/encoders/Mp3LameEncoder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAezD;;GAEG;AACH,qBAAa,qBAAsB,YAAW,YAAY;IACxD,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;OAMG;gBACS,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe;IAc7E;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI;IAYrC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,GAAE,MAAqB,GAAG,IAAI;IAQ7C;;OAEG;IACH,MAAM,IAAI,IAAI;CAMf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1E"}

package/dist/encoders/OggVorbisEncoder.d.ts

@@ -41,8 +41,7 @@ export declare class OggVorbisEncoderWrapper implements AudioEncoder {
 /**
  * Função helper para carregar o script OggVorbisEncoder
  *
- * @param scriptUrl - URL do script OggVorbisEncoder.min.js
+ * @param scriptUrl - URL do script OggVorbisEncoder.min.js (opcional, tenta auto-detectar se não fornecido)
  * @returns Promise que resolve quando o script é carregado
  */
-export declare function loadOggVorbisEncoder(scriptUrl: string): Promise<void>;
-//# sourceMappingURL=OggVorbisEncoder.d.ts.map
+export declare function loadOggVorbisEncoder(scriptUrl?: string): Promise<void>;

package/dist/encoders/OggVorbisEncoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OggVorbisEncoder.d.ts","sourceRoot":"","sources":["../../src/encoders/OggVorbisEncoder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAc/D;;GAEG;AACH,qBAAa,uBAAwB,YAAW,YAAY;IAC1D,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;OAMG;gBACS,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAcnF;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI;IAYrC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,GAAE,MAAoB,GAAG,IAAI;IAQ5C;;OAEG;IACH,MAAM,IAAI,IAAI;CAMf;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqErE"}
+{"version":3,"file":"OggVorbisEncoder.d.ts","sourceRoot":"","sources":["../../src/encoders/OggVorbisEncoder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAe/D;;GAEG;AACH,qBAAa,uBAAwB,YAAW,YAAY;IAC1D,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;OAMG;gBACS,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAcnF;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI;IAYrC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,GAAE,MAAoB,GAAG,IAAI;IAQ5C;;OAEG;IACH,MAAM,IAAI,IAAI;CAMf;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB5E"}

package/dist/encoders/WavAudioEncoder.d.ts

@@ -44,4 +44,3 @@ export declare class WavAudioEncoder implements AudioEncoder {
      */
     private writeString;
 }
-//# sourceMappingURL=WavAudioEncoder.d.ts.map