als-math-audio-composer v1.1.0

als-math-audio-composer

The als-math-audio-composer is a Node.js library designed to generate audio files from mathematical expressions. It supports expressions involving numbers (0-9) and basic arithmetic operators (+, -, *, /) in multiple languages. This library is useful for educational software, accessibility tools, or any application where you need to convert math expressions into audible format.

Installation

Install the package via npm:

npm install als-math-audio-composer

Usage

Here's how to use als-math-audio-composer to generate audio from a mathematical expression:

const MathAudioComposer = require('als-math-audio-composer');

// Create an instance of the MathAudioComposer
const audioComposer = new MathAudioComposer('eng'); // Supports 'eng', 'ru', and 'he'

// Generate audio for a given expression
const audioBuffer = audioComposer.create('1+2');

// Generate HTML audio element for direct embedding
const audioHtml = audioComposer.html('1+2');
console.log(audioHtml);

Constructor

The constructor accepts one optional parameter:

• lang: Specifies the language of the audio files. Default is 'eng'. Available options are 'eng', 'ru', 'he'. The constructor throws an error if an unsupported language is specified, ensuring that only available languages are used.

Methods

create(expression)

• Takes a string expression containing numbers and arithmetic operators.
• Returns a Buffer of the generated audio.
• Example: audioComposer.create('3*4')

html(expression)

• Generates HTML string with a button and an audio element that plays the expression.
• Useful for embedding directly into web pages.
• Example: audioComposer.html('3/4')

cacheAll()

• Preloads all necessary audio files for the specified language into the cache. This is useful for improving performance by loading all audio data into memory at startup.
• Example: audioComposer.cacheAll()

Caching

als-math-audio-composer utilizes a caching mechanism to enhance performance. Once an audio file is read from the disk, it is stored in memory. Subsequent requests for the same audio file will use the cached version, reducing disk I/O and speeding up audio generation.

• Caches are maintained separately for each supported language.
• The cacheAll() method can be used at application startup to preload all necessary audio files into the cache.

Important Notes

• Error Handling: The create method may throw an error if an audio file is missing or inaccessible. This is highly unlikely but could happen in extreme cases. Use try-catch to handle such scenarios.

• Performance: On first run, readFileSync is used, which might block the Node.js event loop. This is generally imperceptible and only occurs at the start.

• Security: The html method does not perform sanitization of the input expression. Ensure that user input is sanitized before passing it to prevent XSS vulnerabilities.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.