Skip to main content

​
Overview

The AudiobookFile class represents a single audio file or chapter in an audiobook. It can represent files from Archive.org, YouTube, or local storage. It also supports chapter slicing for books with embedded chapter metadata.

​
Properties

​
identifier
String?
The audiobook identifier this file belongs to
​
title
String?
The title of this specific file or chapter
​
name
String?
The filename of the audio file
​
url
String?
The URL or local path to the audio file
​
length
double?
The duration of the audio file in seconds
​
track
int?
The track number or chapter position
​
size
int?
The file size in bytes
​
highQCoverImage
String?
URL or path to the high-quality cover image for this file
​
startMs
int?
Chapter start time in milliseconds (from file start). Used for chapter slicing
​
durationMs
int?
Chapter duration in milliseconds. If null, plays to end of file. Used for chapter slicing

​
Constructors

​
AudiobookFile.fromJson(Map json)

Creates an AudiobookFile from Archive.org JSON data. Parameters:
​
json
Map
required
A map containing file data from the Archive.org API
URL Construction:
  • File URL: https://archive.org/download/{identifier}/{name}
  • Cover image: https://archive.org/download/{identifier}/{highQCoverImage}
Map<String, dynamic> jsonData = {
  "identifier": "book123",
  "title": "Chapter 01",
  "name": "book123_01.mp3",
  "track": "1/20",
  "size": "5242880",
  "length": "1234.5",
  "highQCoverImage": "cover.jpg"
};

AudiobookFile file = AudiobookFile.fromJson(jsonData);

​
AudiobookFile.fromYoutubeJson(Map json)

Creates an AudiobookFile from YouTube JSON data. The URL is taken directly from the JSON rather than being constructed. Parameters:
​
json
Map
required
A map containing file data from YouTube
Map<String, dynamic> jsonData = {
  "identifier": "youtube123",
  "title": "Chapter 01",
  "name": "audio_01.mp3",
  "url": "https://youtube.com/audio/123.mp3",
  "track": "1",
  "size": "5242880",
  "length": "1234.5"
};

AudiobookFile file = AudiobookFile.fromYoutubeJson(jsonData);

​
AudiobookFile.fromLocalJson(Map json, String location)

Creates an AudiobookFile from local storage JSON data. Parameters:
​
json
Map
required
A map containing file data
​
location
String
required
The local directory path where the audiobook is stored
URL Construction:
  • File URL: {location}/{url}
  • Cover image: {location}/cover.jpg
Map<String, dynamic> jsonData = {
  "identifier": "local123",
  "title": "Chapter 01",
  "name": "chapter_01.mp3",
  "url": "chapter_01.mp3",
  "track": "1",
  "size": "5242880",
  "length": "1234.5"
};

AudiobookFile file = AudiobookFile.fromLocalJson(jsonData, "/storage/audiobooks/book123");

​
AudiobookFile.fromMap

Creates an AudiobookFile from a map. Parameters:
​
map
Map
required
A map containing all audiobook file properties (Map<dynamic, dynamic>)
Map<String, dynamic> map = {
  "identifier": "book123",
  "title": "Chapter 01",
  "name": "book123_01.mp3",
  "track": 1,
  "size": 5242880,
  "length": 1234.5,
  "url": "https://archive.org/download/book123/book123_01.mp3",
  "highQCoverImage": "https://archive.org/download/book123/cover.jpg",
  "startMs": null,
  "durationMs": null
};

AudiobookFile file = AudiobookFile.fromMap(map);

​
Methods

​
toMap()

Converts the audiobook file to a map. Returns: Map<dynamic, dynamic> 
AudiobookFile file = AudiobookFile.fromJson(jsonData);
Map<dynamic, dynamic> map = file.toMap();

​
toJson()

Converts the audiobook file to a JSON-serializable map. Returns: Map<String, dynamic> 
AudiobookFile file = AudiobookFile.fromJson(jsonData);
Map<String, dynamic> json = file.toJson();

​
Static Methods

​
chapterSlice

Creates a chapter slice from a larger audio file using time offsets. Useful for audiobooks with embedded chapter metadata. Parameters:
​
identifier
String
required
The audiobook identifier
​
url
String
required
The URL or path to the parent audio file
​
parentTitle
String
required
The title of the parent file
​
track
int
required
The chapter/track number
​
chapterTitle
String
required
The title of the chapter. If empty, defaults to ” — Chapter ”
​
startMs
int
required
The start time of the chapter in milliseconds
​
durationMs
int?
The duration of the chapter in milliseconds. If null, plays to end of file
​
highQCoverImage
String?
URL or path to the cover image
Returns: AudiobookFile 
AudiobookFile chapter = AudiobookFile.chapterSlice(
  identifier: "book123",
  url: "https://archive.org/download/book123/full_book.mp3",
  parentTitle: "Pride and Prejudice",
  track: 1,
  chapterTitle: "Chapter 1: It is a truth universally acknowledged",
  startMs: 0,
  durationMs: 1800000, // 30 minutes
  highQCoverImage: "https://archive.org/download/book123/cover.jpg"
);

​
fromJsonArray(List jsonFiles)

Converts a list of JSON objects into a list of AudiobookFile instances. Handles parsing errors gracefully and logs them. Parameters:
​
jsonFiles
List
required
A list of JSON maps from the Archive.org API response
Returns: List<AudiobookFile> 
List<dynamic> jsonArray = [
  {"identifier": "book1", "name": "file1.mp3", "track": "1"},
  {"identifier": "book1", "name": "file2.mp3", "track": "2"}
];

List<AudiobookFile> files = AudiobookFile.fromJsonArray(jsonArray);

​
fromLocalJsonArray(List jsonFiles, String location)

Converts a list of local JSON objects into AudiobookFile instances. Parameters:
​
jsonFiles
List
required
A list of JSON maps
​
location
String
required
The local directory path
Returns: List<AudiobookFile>

​
fromYoutubeJsonArray(List jsonFiles)

Converts a list of YouTube JSON objects into AudiobookFile instances. Parameters:
​
jsonFiles
List
required
A list of JSON maps from YouTube
Returns: List<AudiobookFile>

​
fromDownloadedFiles(String audiobookId)

Scans the downloads directory for MP3 files and creates AudiobookFile instances from them. Extracts metadata using flutter_media_metadata. Parameters:
​
audiobookId
String
required
The audiobook identifier
Returns: Future<Either<String, List<AudiobookFile>>> Returns a Right with the list of files on success, or a Left with an error message on failure. 
final result = await AudiobookFile.fromDownloadedFiles("book123");
result.fold(
  (error) => print("Error: $error"),
  (files) => print("Found ${files.length} files")
);

​
fromLocalFiles(String audiobookId)

Loads AudiobookFile instances from a files.txt JSON file in the local audiobook directory. Parameters:
​
audiobookId
String
required
The audiobook identifier
Returns: Future<Either<String, List<AudiobookFile>>>

​
fromYoutubeFiles(String audiobookId)

Loads AudiobookFile instances from a files.txt JSON file in the YouTube audiobook directory. Parameters:
​
audiobookId
String
required
The audiobook identifier
Returns: Future<Either<String, List<AudiobookFile>>>

​
Helper Methods

The class includes private static helper methods for safe type parsing:
  • _parseTrack(dynamic value) - Safely parses track numbers, handling strings like “1/20”
  • _parseIntSafely(dynamic value) - Safely parses integers from various types
  • _parseDoubleSafely(dynamic value) - Safely parses doubles from various types
These methods log debug messages when parsing errors occur and return sensible defaults (0 or 0.0).

Build docs developers (and LLMs) love

Get started for freeTalk to us