Working with Native Assets in Flutter

When building Flutter applications, you might encounter situations where you need to include platform-specific resources such as images, audio files, videos, or even pre-compiled libraries directly within your project. These resources, known as native assets, can be crucial for achieving certain functionalities or maintaining consistency with platform-specific standards. In this blog post, we’ll explore how to work with native assets in Flutter effectively, covering everything from importing assets to handling them dynamically at runtime.

What are Native Assets?

Native assets are resources bundled directly within your Flutter application that are specific to the underlying platform (e.g., Android or iOS). These assets can include:

  • Images: JPEG, PNG, GIF, and other image formats.
  • Audio Files: MP3, WAV, AAC, etc.
  • Video Files: MP4, AVI, etc.
  • Fonts: TTF, OTF.
  • Data Files: JSON, XML, CSV.
  • Pre-compiled Libraries: Shared libraries (.so for Android, .dylib for iOS).

Why Use Native Assets?

  • Performance: Direct access to assets can sometimes offer better performance compared to downloading resources from the internet.
  • Offline Access: Native assets are available even when the device is offline.
  • Platform Consistency: Ensuring assets are consistent with platform-specific requirements.
  • Embedding Resources: Including resources that are an integral part of the application, such as default configuration files.

How to Work with Native Assets in Flutter

Working with native assets in Flutter involves several steps:

Step 1: Project Setup

Ensure you have a Flutter project ready. If not, create a new one:

flutter create my_flutter_app

Step 2: Adding Assets to Your Project

Create a dedicated folder, such as assets, in your Flutter project’s root directory to store your assets. Here’s an example project structure:

my_flutter_app/
  ├── android/
  ├── ios/
  ├── lib/
  ├── assets/
  │   ├── images/
  │   │   ├── logo.png
  │   ├── audio/
  │   │   ├── sound.mp3
  └── pubspec.yaml

Step 3: Declare Assets in pubspec.yaml

To make Flutter aware of your assets, you need to declare them in the pubspec.yaml file. Add the assets section, specifying the paths to your assets:

flutter:
  assets:
    - assets/images/logo.png
    - assets/audio/sound.mp3

You can also declare entire directories:

flutter:
  assets:
    - assets/images/
    - assets/audio/

After modifying pubspec.yaml, run:

flutter pub get

Step 4: Accessing Assets in Flutter Code

You can access these assets in your Flutter code using the AssetImage or rootBundle classes.

Using AssetImage (for Images)

To display an image from your assets folder, use the AssetImage widget:

import 'package:flutter/material.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Native Assets Example'),
        ),
        body: Center(
          child: Image(image: AssetImage('assets/images/logo.png')),
        ),
      ),
    );
  }
}
Using rootBundle (for Other Assets)

For non-image assets, such as audio files or JSON data, use rootBundle to load the asset’s content:

import 'package:flutter/material.dart';
import 'package:flutter/services.dart' show rootBundle;

class MyApp extends StatelessWidget {
  Future loadAsset() async {
    return await rootBundle.loadString('assets/data/config.json');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Native Assets Example'),
        ),
        body: FutureBuilder(
          future: loadAsset(),
          builder: (context, snapshot) {
            if (snapshot.hasData) {
              return Center(
                child: Text('Data: ${snapshot.data}'),
              );
            } else if (snapshot.hasError) {
              return Center(
                child: Text('Error: ${snapshot.error}'),
              );
            } else {
              return CircularProgressIndicator();
            }
          },
        ),
      ),
    );
  }
}

Working with Platform Channels

For more complex interactions with native assets, such as playing audio files or accessing native libraries, you may need to use Platform Channels.

Example: Playing an Audio File

Suppose you want to play an audio file located in your assets folder. You’ll need to use platform-specific code to play the audio and a platform channel to trigger this functionality from Flutter.

Step 1: Add Dependency

Add the flutter_sound package to your pubspec.yaml file:

dependencies:
  flutter_sound: ^9.2.1

Then run:

flutter pub get
Step 2: Implement Platform-Specific Code

In your Android code (android/app/src/main/kotlin/your_package_name/MainActivity.kt), add the following:

import android.media.MediaPlayer
import android.content.res.AssetFileDescriptor
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel

class MainActivity: FlutterActivity() {
    private val CHANNEL = "audio_channel"
    private var mediaPlayer: MediaPlayer? = null

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler {
            call, result ->
            if (call.method == "playAudioAsset") {
                val assetName = call.argument("assetName")
                if (assetName != null) {
                    try {
                        val descriptor: AssetFileDescriptor = assets.openFd(assetName)
                        mediaPlayer = MediaPlayer().apply {
                            setDataSource(descriptor.fileDescriptor, descriptor.startOffset, descriptor.length)
                            prepare()
                            start()
                        }
                        result.success(true)
                    } catch (e: Exception) {
                        result.error("AUDIO_ERROR", "Failed to play audio asset", e.message)
                    }
                } else {
                    result.error("INVALID_ARGUMENT", "Asset name cannot be null", null)
                }
            } else {
                result.notImplemented()
            }
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        mediaPlayer?.release()
        mediaPlayer = null
    }
}

And in your iOS code (ios/Runner/AppDelegate.swift), add:

import Flutter
import UIKit
import AVFoundation

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
    private var player: AVAudioPlayer?

    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let controller : FlutterViewController = window?.rootViewController as! FlutterViewController
        let audioChannel = FlutterMethodChannel(name: "audio_channel",
                                              binaryMessenger: controller.binaryMessenger)
        audioChannel.setMethodCallHandler { [weak self] (call, result) in
            guard call.method == "playAudioAsset" else {
                result(FlutterMethodNotImplemented)
                return
            }
            if let args = call.arguments as? [String: Any],
               let assetName = args["assetName"] as? String {
                guard let soundURL = Bundle.main.url(forResource: assetName, withExtension: nil, subdirectory: "assets/audio") else {
                    result(FlutterError(code: "ASSET_NOT_FOUND", message: "Could not find asset (assetName)", details: nil))
                    return
                }

                do {
                    self?.player = try AVAudioPlayer(contentsOf: soundURL)
                    self?.player?.prepareToPlay()
                    self?.player?.play()
                    result(true)
                } catch {
                    result(FlutterError(code: "AUDIO_ERROR", message: "Failed to play audio asset", details: error.localizedDescription))
                }
            } else {
                result(FlutterError(code: "INVALID_ARGUMENT", message: "Invalid arguments", details: nil))
            }
        }

        GeneratedPluginRegistrant.register(with: self)
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}
Step 3: Call Platform Channel from Flutter

In your Flutter code:

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

class MyApp extends StatelessWidget {
  static const platform = MethodChannel('audio_channel');

  Future playAudio() async {
    try {
      await platform.invokeMethod('playAudioAsset', {'assetName': 'assets/audio/sound.mp3'});
    } on PlatformException catch (e) {
      print("Failed to play audio: '${e.message}'.");
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Native Assets Example'),
        ),
        body: Center(
          child: ElevatedButton(
            onPressed: playAudio,
            child: Text('Play Audio'),
          ),
        ),
      ),
    );
  }
}

Conclusion

Working with native assets in Flutter involves including and accessing resources directly bundled with your application. You can use AssetImage for images and rootBundle for other assets. For more complex interactions, platform channels allow you to leverage platform-specific capabilities to handle assets effectively. By mastering these techniques, you can build Flutter applications that are both performant and platform-aware, providing a seamless user experience.