패키지, 저장소 및 앱 카테고리 검색

패키지 상세v1.8.1

audio_metadata_reader

오디오 파일용 메타데이터 리더입니다. ID3, Vorbis 주석 및 ILST iTunes를 지원합니다

AndroidiOSmacOSWindowsLinux
30일 다운로드
1.9만
좋아요
45
Pub 점수
160

패키지 설치

flutter pub add audio_metadata_reader

패키지 개요

공개 정보를 바탕으로 생성한 선택 가이드입니다.

오디오 파일에서 메타데이터를 추출하는 Flutter/Dart 패키지로, MP3에 일반적으로 사용되는 ID3 태그, OGG 파일에서 사용되는 Vorbis 주석 및 ILST iTunes 메타데이터를 지원합니다. 개발자들이 여러 플랫폼에서 제목, 아티스트, 앨범, 장르 등 중요한 오디오 정보를 읽을 수 있도록 합니다. 이 패키지는 가볍고 오디오 파일 분석이 필요한 멀티미디어 애플리케이션에 원활하게 통합될 수 있도록 설계되었습니다. Android, iOS, macOS, Windows, Linux에서 작동하므로 크로스플랫폼 오디오 도구에 이상적입니다.

사용 사례

  • 음악 앱에서 곡 메타데이터 읽기
  • 오디오 파일에서 아티스트 및 앨범 정보 추출
  • 미디어 라이브러리 관리 시스템 구축
  • 팟캐스트 애플리케이션을 위한 메타데이터 파싱
  • 오디오 파일 태그 기능 지원

주요 기능

  • ID3, Vorbis 주석 및 ILST 메타데이터를 지원합니다
  • 크로스 플랫폼 호환성
  • 경량이며 통합이 쉬움
  • 구조화된 메타데이터 출력을 제공합니다
  • 일반 오디오 형식과 호환됩니다

적합한 대상

  • 음악 플레이어 개발자
  • 미디어 라이브러리 빌더
  • 오디오 파일 처리 도구
  • 팟캐스트 앱 개발자
  • 크로스 플랫폼 멀티미디어 앱

고려 사항

  • 메타데이터 읽기만 가능하며 편집 불가
  • 모든 오디오 형식을 지원하지 않습니다
  • 메타데이터 파싱은 파일 무결성에 의존합니다
  • 손상된 파일에 대한 내장 오류 처리 없음
  • 일부 플랫폼에서는 적절한 파일 권한이 필요합니다

원본 README

연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.

Audio Metadata Reader

A pure Dart package for reading and writing metadata in various audio formats.

File Format Metadata Format(s) Read Write
MP3 ID3v1, ID3v2 ✅ ✅
MP4 iTunes-style ilst ✅ ✅
FLAC Vorbis Comments ✅ ✅
OGG Vorbis Comments ✅ ❌
Opus Vorbis Comments ✅ ❌
WebM/Matroska Tags / Opus ✅ ❌
WAV RIFF ✅ ✅
AIFF/AIFC IFF chunks ✅ ❌
APE APEv2 ✅ ✅

This package is still under active development. If there's a metadata format you'd like to see supported or specific information you’d like the library to expose, feel free to open an issue.

Usage

Read
import 'dart:io';
import 'package:audio_metadata_reader/audio_metadata_reader.dart';

void main() {
  final track = File("Pieces.mp3");

  // Fetching images can slow down metadata reading
  final metadata = readMetadata(track, getImage: false);

  print(metadata.title);
  print(metadata.album);
}

readMetadata returns the common AudioMetadata view shared by all supported formats. Use readAllMetadata when you need the format-specific metadata object, such as Mp3Metadata, Mp4Metadata, VorbisMetadata, RiffMetadata or ApeMetadata.

import 'dart:io';

import 'package:audio_metadata_reader/audio_metadata_reader.dart';

final track = File("Pieces.mp3");
final metadata = readAllMetadata(track, getImage: false);
print(metadata);
Supported File Extensions

The package currently recognizes these extensions:

.mp3, .flac, .mp4, .m4a, .ape, .ogg, .opus, .wav, .webm, .mkv, .aif, .aiff, .aifc and .mov.

Use supportedFileExtensions when filtering files before parsing:

final isSupported = supportedFileExtensions.any(
  (ext) => file.path.toLowerCase().endsWith(ext),
);
Write
import 'dart:io';
import 'dart:typed_data';

import 'package:audio_metadata_reader/audio_metadata_reader.dart';

void main() {
  final track = File("Pieces.mp3");

  // Use a switch if you want to update metadata based on the file type
  updateMetadata(
    track,
    (metadata) {
      switch (metadata) {
        case Mp3Metadata m:
          m.songName = "New title";
          break;
        case Mp4Metadata m:
          m.title = "New title";
          break;
        case VorbisMetadata m:
          m.title = ["New title"];
          break;
        case RiffMetadata m:
          m.title = "New title";
          break;
        case ApeMetadata m:
          m.title = "New title";
      }
    },
  );

  // Or use extension methods for common metadata updates
  updateMetadata(
    track,
    (metadata) {
      metadata.setTitle("New title");
      metadata.setArtist("New artist");
      metadata.setAlbum("New album");
      metadata.setTrackNumber(1);
      metadata.setYear(DateTime(2014));
      metadata.setLyrics("I'm singing");
      metadata.setGenres(["Rock", "Metal", "Salsa"]);
      metadata.setPictures([
        Picture(Uint8List.fromList([]), "image/png", PictureType.coverFront)
      ]);
    },
  );
}

updateMetadata reads the existing format-specific metadata, applies the callback, then writes it back to the same file while retaining metadata that the callback does not change. For an already constructed metadata object, use replaceMetadata directly:

import 'dart:io';

import 'package:audio_metadata_reader/audio_metadata_reader.dart';

final metadata = Mp3Metadata()..songName = "New title";
replaceMetadata(File("Pieces.mp3"), metadata);

replaceMetadata reconstructs the supported metadata from the object you provide. It is destructive: tags that are not represented by that object may be removed. writeMetadata is deprecated and behaves the same way; use updateMetadata when you need to preserve existing metadata that you are not editing.

The replacement is written to a temporary file in the same directory and renamed into place only after the writer completes, so a failed write leaves the original file untouched. The format-specific writer classes use the same atomic write path.

The common setter extension also provides setTrackTotal and setCD. Some formats do not support every field; unsupported setters are intentionally ignored for those formats.

MP4 metadata can also contain Chapter markers. OGG, Opus and AIFF/AIFC are currently read-only; metadata writing is supported for MP3, MP4, FLAC, WAV and APE files.

Performance

On my laptop with an SSD, the library can process metadata from 3,392 tracks in under 200ms — assuming covers aren't fetched. With covers, it's around 400ms.

import 'dart:io';
import 'package:audio_metadata_reader/audio_metadata_reader.dart';

void main() {
  final folder = Directory(r"music folder")
      .listSync(recursive: true)
      .whereType<File>()
      .where(
        (file) => supportedFileExtensions.any(
          (ext) => file.path.toLowerCase().endsWith(ext),
        ),
      )
      .toList();

  print("Number of tracks: ${folder.length}");

  final start = DateTime.now();

  for (final file in folder) {
    readMetadata(file, getImage: false);
  }

  final end = DateTime.now();
  print("Duration: ${end.difference(start)}");
}
Compare with FFmpeg/libavformat

The repository includes a standalone benchmark that recursively scans a music directory and reads metadata without loading cover images:

dart run tool/benchmark_metadata.dart --backend both --runs 3

It defaults to ~/Music. Use --music PATH for another directory and --backend library to measure only this package. The ffprobe comparison uses FFmpeg/libavformat through the ffprobe executable and requests only format_tags; its timing includes one process launch per file.

To list the files that fail to parse, run the diagnostic script:

dart run tool/find_metadata_errors.dart --music ~/Music

It prints each failing path, the exception message, and an error summary. Add --stack-traces when investigating a parser failure in detail.

Anonymize a Music Track

If you need to report an issue or test the library without sharing private audio, you can anonymize a track by replacing its audio with white noise using ffmpeg:

ffmpeg -i <your_track> -f lavfi -t 5 -i "anoisesrc=color=white:duration=5" -map_metadata 0 -map 1:a -t 5 <output_track>

카테고리

의존성

의존성 목록 3 개

소스 저장소

이 패키지를 사용하는 프로젝트