Nyx Converter

A Flutter package that provides a simple and powerful API for converting, inspecting, and processing audio and video files.

📖 Overview

nyx_converter is a Flutter package that provides a simple and powerful API for working with media files.

It allows Flutter applications to:

🔄 Convert media containers
🎬 Change video and audio codecs
🎚️ Configure bitrates
📊 Monitor conversion progress in real time
🖥️ Receive FPS and conversion speed updates
❌ Cancel running conversions
✅ Validate media files before processing
🔍 Read detailed media information
🖼️ Generate media thumbnails

Nyx Converter handles FFmpeg command generation internally, allowing developers to work with media files without manually writing FFmpeg commands.

✨ Features

Feature	Status
Media container conversion	✅
Video codec conversion	✅
Audio codec conversion	✅
Audio bitrate control	✅
Video bitrate control	✅
Real-time progress callback	✅
FPS monitoring	✅
Conversion speed monitoring	✅
Cancel running conversions	✅
Input media validation	✅
Output validation	✅
Media information	✅
Media thumbnail generation	✅
Video resize	🚧
Audio frequency control	🚧
Audio channel layout	🚧

📦 Installation

Add the package to your pubspec.yaml.

dependencies:
  nyx_converter: ^{{VERSION}}

Install dependencies:

flutter pub get

📱 Platform Support

Platform	Minimum Requirement
Android	API 24+
Kotlin	1.8.22+
iOS	14.0+
macOS	10.15+
Windows	Windows 10+ (x86_64)

Supported architectures

🤖 Android

arm-v7a
arm-v7a-neon
arm64-v8a
x86
x86_64

🍎 iOS

arm64 devices
arm64 / x86_64 simulators

🖥️ macOS

arm64
x86_64

🪟 Windows

x86_64

🚀 Quick Start

Import Nyx Converter:

import 'package:nyx_converter/nyx_converter.dart';

Convert a media file:

await NyxConverter.convertTo(
  '/storage/emulated/0/DCIM/input.mp4',
  '/storage/emulated/0/Movies',
  container: NyxContainer.mp4,
  execution: (
    status, {
    progress,
    fps,
    speed,
    errorMessage,
  }) {
    switch (status) {
      case NyxStatus.running:
        print('Progress: $progress%');
        break;

      case NyxStatus.completed:
        print('Conversion completed');
        break;

      case NyxStatus.failed:
        print(errorMessage);
        break;

      case NyxStatus.cancel:
        print('Conversion cancelled');
        break;
    }
  },
);

⚙️ Conversion Options

📦 Container

Define the output media container:

container: NyxContainer.mp4,

📚 Available containers: Wiki → Container

🎬 Video Codec

Change the video encoding codec:

videoCodec: NyxVideoCodec.h264,

📚 Available codecs: Wiki → Video Codec

🔊 Audio Codec

Change the audio encoding codec:

audioCodec: NyxAudioCodec.aac,

📚 Available codecs: Wiki → Audio Codec

🎚️ Bitrate

Configure output quality and file size:

audioBitrate: 192,
videoBitrate: 5,

📚 More information: Wiki → Bitrate

📝 Output File Name

By default, Nyx Converter keeps the original filename.

You can customize it:

fileName: 'converted_video',

🐛 Debug Logs

Enable detailed FFmpeg logs:

debugMode: true,

📡 Execution Callback

The execution callback provides real-time conversion updates.

The callback is optional. If it is not provided, conversion runs silently.

execution: (
  NyxStatus status, {
  double? progress,
  double? fps,
  double? speed,
  String? errorMessage,
}) {

},

Status

Status	Description
`NyxStatus.running`	Conversion is running
`NyxStatus.completed`	Conversion finished successfully
`NyxStatus.failed`	Conversion failed
`NyxStatus.cancel`	Conversion cancelled

Callback Data

Property	Description
`progress`	Conversion percentage from `0` to `100`
`fps`	Current processing frames per second
`speed`	Current FFmpeg processing speed
`errorMessage`	Error details when conversion fails

🛡️ Automatic Validation

Before starting conversion, Nyx Converter validates:

✅ Input file exists
✅ Media file is readable
✅ Media contains valid streams
✅ Output directory exists
✅ Output file does not already exist

If validation fails, conversion will not start and:

NyxStatus.failed

will be returned through the execution callback.

🛑 Cancel Conversion

Cancel all active conversions:

NyxConverter.kill();

🔍 Media Information

Get detailed information about an audio or video file:

final NyxMediaInfo info = await NyxConverter.getMediaInfo(
  '/storage/emulated/0/Movies/video.mp4',
);

print('File: ${info.fileName}');
print('Format: ${info.format}');
print('Duration: ${info.duration}');
print('Has video: ${info.hasVideo}');
print('Has audio: ${info.hasAudio}');

Video and audio information is available through info.video and info.audio.

📚 Full documentation and examples: Wiki → Media Info

🖼️ Media Thumbnail

Generate a thumbnail from a media file:

final Uint8List thumbnail = await NyxConverter.getThumbnail(
  '/storage/emulated/0/Movies/video.mp4',
  time: const Duration(seconds: 5),
);

Display it in Flutter:

Image.memory(thumbnail);

📚 Full documentation and examples: Wiki → Thumbnail

📚 Documentation

Detailed documentation is available in the Wiki:

🔗 Wiki: https://github.com/xaus-group/nyx_converter/wiki

🤝 Contributing

Contributions, issues, and feature requests are welcome.

📄 Please read the contribution guide.

📄 License

Nyx Converter is licensed under the GNU LGPL v3.0 license.