examples

Signed-off-by: ale <ale@manalejandro.com>

.gitignore

@@ -63,6 +63,10 @@ example_*.i2m
 *.test.js
 *.spec.js
 
+# Example generated files
+examples/risitas_with_chiquito.i2m
+examples/extracted_*
+
 # Build directories
 dist/
 build/

README.md

@@ -25,6 +25,24 @@ npm install -g img2mp3
 npm install img2mp3
 ```
 
+## Quick Start
+
+To see IMG2MP3 in action, run the included example:
+
+```bash
+# Clone the repository
+git clone https://github.com/ale/img2mp3.git
+cd img2mp3
+
+# Install dependencies
+npm install
+
+# Run the example with sample files
+npm run example
+```
+
+This will demonstrate encoding, decoding, and playing with the included sample files (`risitas.jpg` and `chiquito-cobarde.mp3`).
+
 ## Usage
 
 ### Command Line Interface

examples/README.md

@@ -0,0 +1,50 @@
+# Examples
+
+This directory contains example files and usage demonstrations for IMG2MP3.
+
+## Files
+
+- `basic_usage.js` - Complete example showing all functionality
+- `risitas.jpg` - Sample image file for testing
+- `chiquito-cobarde.mp3` - Sample audio file for testing
+
+## Running the Example
+
+To run the complete example with the provided files:
+
+```bash
+# From the project root directory
+npm run example
+
+# Or run directly
+node examples/basic_usage.js
+```
+
+## What the Example Does
+
+1. **Encodes** the MP3 file into the image, creating a `.i2m` file
+2. **Gets information** about the created `.i2m` file
+3. **Plays** the embedded audio (if an audio player is available)
+4. **Decodes** the `.i2m` file back to separate image and MP3 files
+
+## Expected Output
+
+The example will create the following files in the `examples` directory:
+
+- `risitas_with_chiquito.i2m` - The image with embedded audio
+- `extracted_risitas.png` - The extracted original image
+- `extracted_chiquito.mp3` - The extracted audio file
+
+## Testing Different Files
+
+You can replace `risitas.jpg` and `chiquito-cobarde.mp3` with your own files to test with different content. Just make sure to update the filenames in `basic_usage.js` accordingly.
+
+## Audio Players
+
+For the playback functionality to work, you need one of these audio players installed:
+
+- **Linux**: `sudo apt install mpg123` or `sudo apt install mpv`
+- **macOS**: `brew install mpg123` or `brew install mpv`
+- **Windows**: Install [mpv](https://mpv.io/installation/)
+
+If no audio player is available, the example will show a warning but continue with the other functionality.

examples/basic_usage.js

@@ -7,48 +7,59 @@ async function example() {
   console.log('🎵 IMG2MP3 Example Usage\n');
   
   try {
-    // Note: You'll need to provide actual image and MP3 files
+    // Using the actual files in the examples directory
-    const imagePath = 'sample_image.jpg'; // Replace with actual image
+    const imagePath = path.join(__dirname, 'risitas.jpg');
-    const mp3Path = 'sample_audio.mp3';   // Replace with actual MP3
+    const mp3Path = path.join(__dirname, 'chiquito-cobarde.mp3');
-    const outputPath = 'example_output.i2m';
+    const outputPath = path.join(__dirname, 'risitas_with_chiquito.i2m');
     
     console.log('1. Encoding MP3 into image...');
-    // Uncomment when you have actual files:
+    console.log(`   Image: ${path.basename(imagePath)}`);
-    // const encodeResult = await img2mp3.encode(imagePath, mp3Path, outputPath);
+    console.log(`   Audio: ${path.basename(mp3Path)}`);
-    // console.log('✅ Encoding successful!');
+    
-    // console.log(`   Output size: ${encodeResult.outputSize} bytes`);
+    const encodeResult = await img2mp3.encode(imagePath, mp3Path, outputPath);
-    // console.log(`   Container image: ${encodeResult.imageSize}\n`);
+    console.log('✅ Encoding successful!');
+    console.log(`   Original image: ${formatBytes(encodeResult.originalImageSize)}`);
+    console.log(`   MP3 file: ${formatBytes(encodeResult.mp3Size)}`);
+    console.log(`   Output size: ${formatBytes(encodeResult.outputSize)}`);
+    console.log(`   Container image: ${encodeResult.imageSize}\n`);
     
     console.log('2. Getting file information...');
-    // Uncomment when you have an actual .i2m file:
+    const info = await img2mp3.getInfo(outputPath);
-    // const info = await img2mp3.getInfo(outputPath);
+    if (info.isValid) {
-    // if (info.isValid) {
+      console.log('✅ Valid .i2m file detected!');
-    //   console.log('✅ Valid .i2m file detected!');
+      console.log(`   Embedded audio: ${formatBytes(info.mp3Size)}`);
-    //   console.log(`   Embedded audio: ${info.mp3Size} bytes`);
+      console.log(`   Original image: ${formatBytes(info.originalImageSize)}`);
-    //   console.log(`   Original image: ${info.originalImageSize} bytes\n`);
+      console.log(`   Container dimensions: ${info.dimensions}\n`);
-    // }
+    }
     
     console.log('3. Playing embedded audio...');
-    // Uncomment when you have an actual .i2m file:
+    console.log('   (Press Ctrl+C to stop playback)');
-    // await img2mp3.play(outputPath);
+    try {
-    // console.log('✅ Playback finished!\n');
+      await img2mp3.play(outputPath);
+      console.log('✅ Playback finished!\n');
+    } catch (playError) {
+      console.log(`⚠️  Playback failed: ${playError.message}`);
+      console.log('   (This is normal if no audio player is installed)\n');
+    }
     
     console.log('4. Decoding back to separate files...');
-    // Uncomment when you have an actual .i2m file:
+    const extractedImagePath = path.join(__dirname, 'extracted_risitas.png');
-    // const decodeResult = await img2mp3.decode(
+    const extractedMp3Path = path.join(__dirname, 'extracted_chiquito.mp3');
-    //   outputPath,
-    //   'extracted_image.png',
-    //   'extracted_audio.mp3'
-    // );
-    // console.log('✅ Decoding successful!');
-    // console.log(`   Extracted image: ${decodeResult.extractedImageSize} bytes`);
-    // console.log(`   Extracted audio: ${decodeResult.extractedMp3Size} bytes`);
     
-    console.log('\n🎉 Example completed!');
+    const decodeResult = await img2mp3.decode(
-    console.log('\nTo run this example with real files:');
+      outputPath,
-    console.log('1. Place an image file named "sample_image.jpg" in this directory');
+      extractedImagePath,
-    console.log('2. Place an MP3 file named "sample_audio.mp3" in this directory');
+      extractedMp3Path
-    console.log('3. Uncomment the code above and run again');
+    );
+    console.log('✅ Decoding successful!');
+    console.log(`   Extracted image: ${path.basename(extractedImagePath)} (${formatBytes(decodeResult.extractedImageSize)})`);
+    console.log(`   Extracted audio: ${path.basename(extractedMp3Path)} (${formatBytes(decodeResult.extractedMp3Size)})`);
+    
+    console.log('\n🎉 Example completed successfully!');
+    console.log('\nGenerated files:');
+    console.log(`📁 ${path.basename(outputPath)} - The image with embedded audio`);
+    console.log(`🖼️  ${path.basename(extractedImagePath)} - Extracted image`);
+    console.log(`🎵 ${path.basename(extractedMp3Path)} - Extracted audio`);
     
   } catch (error) {
     console.error('❌ Error:', error.message);
@@ -58,5 +69,20 @@ async function example() {
   }
 }
 
+/**
+ * Format bytes to human readable format
+ */
+function formatBytes(bytes, decimals = 2) {
+  if (bytes === 0) return '0 Bytes';
+
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
+}
+
 // Run the example
 example().catch(console.error);