Thumbnail

The getThumbnail API generates an image thumbnail from a media file.

The thumbnail is returned directly as a Uint8List, so no output path is required.

This makes it easy to display the thumbnail in Flutter using Image.memory.

---

Method

Future<Uint8List> getThumbnail(
  String inputPath, {
  Duration? time,
});

---

Parameters

inputPath

The path of the media file.

'/storage/emulated/0/Movies/video.mp4'

Example:

final thumbnail = await NyxConverter.getThumbnail(
  '/path/to/video.mp4',
);

---

time

The position in the media file where the thumbnail should be generated.

Type:

Duration?

Example:

time: const Duration(seconds: 5),

This attempts to generate the thumbnail from approximately 5 seconds into the media.

If time is not provided, the default position is determined by the package implementation.

---

Basic Example

import 'dart:typed_data';

import 'package:nyx_converter/nyx_converter.dart';

final Uint8List thumbnail =
    await NyxConverter.getThumbnail(
  '/path/to/video.mp4',
  time: const Duration(seconds: 5),
);

---

Display in Flutter

Because the method returns Uint8List, you can display the thumbnail directly with Image.memory.

Image.memory(thumbnail);

Complete example:

Uint8List? thumbnail;

Future<void> loadThumbnail() async {
  final result = await NyxConverter.getThumbnail(
    '/path/to/video.mp4',
    time: const Duration(seconds: 5),
  );

  setState(() {
    thumbnail = result;
  });
}

Then:

if (thumbnail != null) {
  Image.memory(
    thumbnail!,
    fit: BoxFit.cover,
  );
}

---

Thumbnail From a Specific Time

You can select a position using Duration.

5 seconds

final thumbnail = await NyxConverter.getThumbnail(
  inputPath,
  time: const Duration(seconds: 5),
);

30 seconds

final thumbnail = await NyxConverter.getThumbnail(
  inputPath,
  time: const Duration(seconds: 30),
);

1 minute

final thumbnail = await NyxConverter.getThumbnail(
  inputPath,
  time: const Duration(minutes: 1),
);

1 minute and 30 seconds

final thumbnail = await NyxConverter.getThumbnail(
  inputPath,
  time: const Duration(
    minutes: 1,
    seconds: 30,
  ),
);

---

Using Media Duration

You can combine getMediaInfo with getThumbnail.

For example, generate a thumbnail from the middle of a media file:

final info = await NyxConverter.getMediaInfo(inputPath);

final duration = info.duration;

final thumbnail = await NyxConverter.getThumbnail(
  inputPath,
  time: duration == null
      ? null
      : Duration(
          milliseconds:
              duration.inMilliseconds ~/ 2,
        ),
);

This is useful when you want a thumbnail from the middle of a video instead of always using the beginning.

---

Complete Flutter Example

import 'dart:typed_data';

import 'package:flutter/material.dart';
import 'package:nyx_converter/nyx_converter.dart';

class ThumbnailExample extends StatefulWidget {
  const ThumbnailExample({super.key});

  @override
  State<ThumbnailExample> createState() =>
      _ThumbnailExampleState();
}

class _ThumbnailExampleState
    extends State<ThumbnailExample> {
  Uint8List? thumbnail;
  bool loading = false;

  Future<void> loadThumbnail() async {
    setState(() {
      loading = true;
    });

    try {
      final result = await NyxConverter.getThumbnail(
        '/path/to/video.mp4',
        time: const Duration(seconds: 5),
      );

      if (!mounted) return;

      setState(() {
        thumbnail = result;
      });
    } catch (e) {
      debugPrint('Thumbnail error: $e');
    } finally {
      if (mounted) {
        setState(() {
          loading = false;
        });
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Thumbnail Example'),
      ),
      body: Center(
        child: loading
            ? const CircularProgressIndicator()
            : thumbnail != null
                ? Image.memory(
                    thumbnail!,
                    fit: BoxFit.cover,
                  )
                : ElevatedButton(
                    onPressed: loadThumbnail,
                    child: const Text(
                      'Generate Thumbnail',
                    ),
                  ),
      ),
    );
  }
}

---

FutureBuilder Example

You can also use FutureBuilder.

FutureBuilder<Uint8List>(
  future: NyxConverter.getThumbnail(
    inputPath,
    time: const Duration(seconds: 5),
  ),
  builder: (context, snapshot) {
    if (snapshot.connectionState ==
        ConnectionState.waiting) {
      return const CircularProgressIndicator();
    }

    if (snapshot.hasError) {
      return Text(
        'Failed to generate thumbnail',
      );
    }

    if (!snapshot.hasData) {
      return const SizedBox();
    }

    return Image.memory(
      snapshot.data!,
      fit: BoxFit.cover,
    );
  },
);

---

Save Thumbnail to a File

Although getThumbnail does not require an output path, you can save the returned bytes yourself if needed.

import 'dart:io';

final thumbnail = await NyxConverter.getThumbnail(
  inputPath,
  time: const Duration(seconds: 5),
);

final file = File(
  '/path/to/output/thumbnail.jpg',
);

await file.writeAsBytes(thumbnail);

---

Error Handling

Always handle errors when generating thumbnails.

try {
  final thumbnail =
      await NyxConverter.getThumbnail(
    inputPath,
    time: const Duration(seconds: 5),
  );

  // Use thumbnail.
} catch (e) {
  print('Failed to generate thumbnail: $e');
}

Possible causes of failure include:

• The input file does not exist
• The media file is not readable
• The file is not a supported media file
• The requested position cannot be processed
• Thumbnail extraction fails

---

Memory Usage

The thumbnail is returned as an in-memory Uint8List.

This is convenient for Flutter applications:

Image.memory(thumbnail);

However, if your application generates many thumbnails, consider managing memory carefully and releasing references to thumbnails that are no longer needed.