@gexein/wasm

WebAssembly модули для высокопроизводительной обработки медиафайлов

@gexein/wasm предоставляет оптимизированные WASM модули для обработки изображений и аудио непосредственно в браузере с производительностью, близкой к нативной.

🚀 Особенности

• ⚡ Высокая производительность - обработка на скорости близкой к нативной
• 🔒 Приватность - файлы не покидают устройство пользователя
• 📦 Малый размер - оптимизированные WASM модули
• 🎨 Множество фильтров - яркость, контраст, насыщенность, размытие и др.
• 🎵 Аудио обработка - нормализация, обрезка, эффекты (эхо, реверберация)
• 💪 TypeScript - полная типизация
• 🌐 Кроссплатформенность - работает во всех современных браузерах

📦 Установка

npm install @gexein/wasm
# или
yarn add @gexein/wasm
# или
pnpm add @gexein/wasm

🔧 Требования

• Node.js 16+
• Современный браузер с поддержкой WebAssembly
• TypeScript 4.0+ (для разработки)

📖 Использование

Обработка изображений

import { processImage, ImageOptions } from '@gexein/wasm';

// Получение пиксельных данных из изображения
const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d')!;
const imageData = ctx.getImageData(0, 0, width, height);
const pixelData = imageData.data;

// Опции обработки
const options: ImageOptions = {
  width: 800,              // Новая ширина
  height: 600,             // Новая высота
  quality: 85,             // Качество сжатия
  format: 'jpeg',          // Формат: 'jpeg', 'png', 'webp'
  grayscale: false,         // Черно-белый
  brightness: 10,          // Яркость (-255 до 255)
  contrast: 5,             // Контраст (-255 до 255)
  saturation: 0,           // Насыщенность (-100 до 100)
};

// Обработка изображения
const result = await processImage(
  pixelData,
  width,
  height,
  4, // RGBA
  options
);

// Создание нового изображения из результата
const newImageData = new ImageData(
  new Uint8ClampedArray(result.data),
  result.width,
  result.height
);
ctx.putImageData(newImageData, 0, 0);

Отдельные функции обработки изображений

import {
  resizeImage,
  applyBrightness,
  applyContrast,
  convertToGrayscale,
  applyBlur
} from '@gexein/wasm';

// Изменение размера
const resized = await resizeImage(
  pixelData,
  originalWidth,
  originalHeight,
  800,
  600,
  4 // channels
);

// Яркость
const brightened = await applyBrightness(
  pixelData,
  width,
  height,
  4,
  20 // brightness value
);

// Контраст
const contrasted = await applyContrast(
  pixelData,
  width,
  height,
  4,
  30 // contrast value
);

// Черно-белый
const grayscale = await convertToGrayscale(
  pixelData,
  width,
  height,
  4
);

// Размытие
const blurred = await applyBlur(
  pixelData,
  width,
  height,
  4,
  3 // blur radius
);

Обработка аудио

import { processAudio, AudioOptions } from '@gexein/wasm';

// Получение аудио данных
const audioContext = new AudioContext();
const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
const channelData = audioBuffer.getChannelData(0); // Первый канал

// Опции обработки
const options: AudioOptions = {
  sampleRate: 44100,        // Частота дискретизации
  channels: 2,                // Количество каналов
  trimStart: 0,              // Начало обрезки (в сэмплах)
  trimEnd: channelData.length, // Конец обрезки (в сэмплах)
  volume: 1.2,               // Громкость (1.0 - оригинальная)
  normalize: true,            // Нормализация
  fadeInDuration: 44100,      // Fade-in (1 секунда при 44.1kHz)
  fadeOutDuration: 44100,     // Fade-out (1 секунда при 44.1kHz)
  speed: 1.0,                // Скорость воспроизведения
};

// Обработка аудио
const result = await processAudio(channelData, options);

// Создание нового AudioBuffer
const newBuffer = audioContext.createBuffer(
  result.channels,
  result.numSamples,
  result.sampleRate
);
newBuffer.copyToChannel(result.data, 0);

Отдельные функции обработки аудио

import {
  normalizeAudio,
  adjustVolume,
  trimAudio,
  applyFadeIn,
  applyFadeOut,
  changeSpeed,
  applyEcho,
  applyReverb
} from '@gexein/wasm';

// Нормализация
const normalized = await normalizeAudio(audioData);

// Изменение громкости
const louder = await adjustVolume(audioData, 1.5);

// Обрезка
const trimmed = await trimAudio(
  audioData,
  44100,  // start sample
  88200   // end sample
);

// Fade-in
const fadedIn = await applyFadeIn(
  audioData,
  22050 // 0.5 секунды при 44.1kHz
);

// Fade-out
const fadedOut = await applyFadeOut(
  audioData,
  22050 // 0.5 секунды при 44.1kHz
);

// Изменение скорости
const faster = await changeSpeed(audioData, 1.5);

// Эхо
const echo = await applyEcho(
  audioData,
  22050, // delay samples (0.5 секунды)
  0.5    // decay (0.0 - 1.0)
);

// Реверберация
const reverb = await applyReverb(
  audioData,
  0.7, // room size (0.0 - 1.0)
  0.5   // damping (0.0 - 1.0)
);

📚 API Reference

ImageOptions

interface ImageOptions {
  width?: number;        // Ширина выходного изображения
  height?: number;       // Высота выходного изображения
  quality?: number;      // Качество сжатия (1-100)
  format?: 'jpeg' | 'png' | 'webp';  // Формат
  grayscale?: boolean;    // Черно-белый
  brightness?: number;   // Яркость (-255 до 255)
  contrast?: number;     // Контраст (-255 до 255)
  saturation?: number;   // Насыщенность (-100 до 100)
}

AudioOptions

interface AudioOptions {
  sampleRate?: number;       // Частота дискретизации
  channels?: number;         // Количество каналов
  trimStart?: number;        // Начало обрезки (в сэмплах)
  trimEnd?: number;          // Конец обрезки (в сэмплах)
  volume?: number;           // Громкость (1.0 - оригинальная)
  normalize?: boolean;       // Нормализовать
  fadeInDuration?: number;    // Fade-in (в сэмплах)
  fadeOutDuration?: number;   // Fade-out (в сэмплах)
  speed?: number;           // Скорость воспроизведения
}

Функции обработки изображений

• processImage(data, width, height, channels, options) - Полная обработка
• resizeImage(data, inW, inH, outW, outH, channels) - Изменение размера
• applyBrightness(data, width, height, channels, brightness) - Яркость
• applyContrast(data, width, height, channels, contrast) - Контраст
• convertToGrayscale(data, width, height, channels) - Черно-белый
• applyBlur(data, width, height, channels, radius) - Размытие

Функции обработки аудио

• processAudio(data, options) - Полная обработка
• normalizeAudio(data) - Нормализация
• adjustVolume(data, volume) - Громкость
• trimAudio(data, start, end) - Обрезка
• applyFadeIn(data, duration) - Fade-in
• applyFadeOut(data, duration) - Fade-out
• changeSpeed(data, speed) - Скорость
• applyEcho(data, delay, decay) - Эхо
• applyReverb(data, roomSize, damping) - Реверберация

🏗️ Разработка

Клонирование репозитория

git clone https://github.com/your-org/digital-workshop-wasm.git
cd digital-workshop-wasm

Установка зависимостей

npm install

Сборка WASM модулей

Для сборки WASM модулей требуется Emscripten:

# Установка Emscripten (если еще не установлен)
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

# Сборка проекта
npm run build

Разработка

# Режим разработки с watch
npm run dev

# Запуск тестов
npm test

# Тесты с покрытием
npm run test:coverage

# Линтер
npm run lint

# Форматирование
npm run format

🧪 Тестирование

# Все тесты
npm test

# Watch режим
npm run test:watch

# С покрытием
npm run test:coverage

📦 Публикация

# Сборка
npm run build

# Тесты
npm test

# Публикация в npm
npm publish

🔒 Безопасность

• Все операции выполняются локально в браузере
• Файлы не отправляются на сервер
• Валидация входных данных
• Безопасное управление памятью

🌐 Поддержка браузеров

• Chrome 57+
• Firefox 52+
• Safari 11+
• Edge 16+

📄 Лицензия

MIT License - см. файл LICENSE

🤝 Вклад в проект

Мы приветствуем вклад в проект! Пожалуйста:

1. Fork репозитория
2. Создайте feature branch
3. Commit ваши изменения
4. Push в branch
5. Создайте Pull Request

🙏 Благодарности

• Emscripten team за отличный инструмент компиляции в WASM
• WebAssembly community за поддержку и развитие технологии

📝 Changelog

1.0.6 (2026-04-17)

• 🐛 Исправлены импорты WASM модулей - теперь используются абсолютные пути через пакет
• ✨ Упрощена структура пакета - все файлы в корне
• 📝 Обновлена документация

1.0.5 (2026-04-17)

• 🐛 Изменена структура пакета для совместимости с Vite и другими бандлерами
• ✨ Файлы теперь компилируются в корень проекта вместо dist/
• 📝 Обновлена документация

1.0.4 (2026-04-17)

• 🐛 Исправлена загрузка WASM модулей с флагом MODULARIZE=1
• ✨ Добавлен вызов функции-фабрики для получения экземпляра модуля
• 📝 Обновлена документация

1.0.3 (2026-04-17)

• 🐛 Исправлена структура пакета для работы с Vite и другими бандлерами
• ✨ WASM файлы теперь копируются в dist/compiled/
• 📝 Обновлена документация

1.0.2 (2026-04-17)

• 🐛 Исправлены пути к main и types в package.json
• ✨ Улучшена совместимость с TypeScript проектами
• 📝 Обновлена документация

1.0.1 (2026-04-17)

• 🐛 Исправлена проблема с путями импорта WASM модулей
• ✨ Добавлен динамический импорт с fallback для поддержки локальной разработки и установленного пакета
• 📝 Обновлена документация
• 🔧 Улучшена совместимость с различными средами сборки

1.0.0 (2026-04-16)

• 🎉 Первый релиз
• ✨ Обработка изображений (изменение размера, фильтры)
• ✨ Обработка аудио (нормализация, эффекты)
• 📝 Полная TypeScript типизация
• 📚 Документация API

Создано с ❤️ для Digital Workshop