Skip to main content

​
Overview

The LocalAudiobook class represents an audiobook that has been imported from the user’s device storage. Unlike remote audiobooks from LibriVox, these are managed entirely locally and can include user-added metadata.

​
Properties

​
title
String
required
The title of the audiobook
​
author
String
required
The author of the audiobook
​
folderPath
String
required
The file system path to the folder containing the audiobook files
​
coverImagePath
String?
The file system path to the cover image, if available
​
audioFiles
List<String>
required
A list of paths to the audio files that make up this audiobook
​
totalDuration
Duration?
The total playback duration of all audio files combined
​
dateAdded
DateTime
required
The date and time when this audiobook was added to the library
​
lastModified
DateTime
required
The date and time when this audiobook was last modified
​
description
String?
A text description of the audiobook
​
genre
String?
The genre or category of the audiobook
​
rating
double?
User rating for the audiobook
​
id
String
required
A unique identifier for the audiobook

​
Constructor

​
Constructor

Creates a new LocalAudiobook instance. Parameters:
​
title
String
required
The title of the audiobook
​
author
String
required
The author of the audiobook
​
folderPath
String
required
The folder path containing the audiobook files
​
coverImagePath
String?
The path to the cover image
​
audioFiles
List<String>
required
List of audio file paths
​
totalDuration
Duration?
Total duration of the audiobook
​
dateAdded
DateTime
required
When the audiobook was added
​
lastModified
DateTime
required
When the audiobook was last modified
​
description
String?
Description text
​
genre
String?
Genre or category
​
rating
double?
User rating
​
id
String
required
Unique identifier
LocalAudiobook audiobook = LocalAudiobook(
  id: "local_123",
  title: "The Great Gatsby",
  author: "F. Scott Fitzgerald",
  folderPath: "/storage/audiobooks/great_gatsby",
  coverImagePath: "/storage/audiobooks/great_gatsby/cover.jpg",
  audioFiles: [
    "/storage/audiobooks/great_gatsby/chapter_01.mp3",
    "/storage/audiobooks/great_gatsby/chapter_02.mp3",
  ],
  totalDuration: Duration(hours: 4, minutes: 30),
  dateAdded: DateTime.now(),
  lastModified: DateTime.now(),
  description: "A classic novel of the Jazz Age",
  genre: "Fiction",
  rating: 4.5,
);

​
Getters

​
firstAudioFile

Returns the path to the first audio file in the audiobook, or null if there are no audio files. Returns: String? 
String? firstFile = audiobook.firstAudioFile;

​
hasCoverImage

Checks whether the audiobook has a cover image. Returns: bool 
if (audiobook.hasCoverImage) {
  // Display cover image
}

​
formattedDuration

Returns a human-readable string representation of the total duration. Returns: String Format:
  • If duration is unknown: “Unknown”
  • If hours > 0: “h m”
  • If hours = 0: “m”
String duration = audiobook.formattedDuration;
// Example output: "4h 30m" or "45m"

​
Methods

​
copyWith

Creates a copy of the audiobook with optionally updated fields. Parameters:
​
title
String?
Updated title
​
author
String?
Updated author
​
folderPath
String?
Updated folder path
​
coverImagePath
String?
Updated cover image path
​
audioFiles
List<String>?
Updated audio files list
​
totalDuration
Duration?
Updated total duration
​
dateAdded
DateTime?
Updated date added
​
lastModified
DateTime?
Updated last modified date
​
description
String?
Updated description
​
genre
String?
Updated genre
​
rating
double?
Updated rating
​
id
String?
Updated identifier
Returns: LocalAudiobook 
LocalAudiobook updatedBook = audiobook.copyWith(
  rating: 5.0,
  description: "An updated description",
);

​
toMap()

Converts the audiobook to a map suitable for Hive storage. Returns: Map<String, dynamic> Note: DateTime values are converted to milliseconds since epoch, and Duration is converted to milliseconds. 
Map<String, dynamic> map = audiobook.toMap();
// Can be stored in Hive database

​
toString()

Returns a string representation of the audiobook. Returns: String 
print(audiobook.toString());
// Output: LocalAudiobook(id: local_123, title: The Great Gatsby, author: F. Scott Fitzgerald, folderPath: /storage/audiobooks/great_gatsby)

​
Static Methods

​
fromMap

Creates a LocalAudiobook instance from a map (typically retrieved from Hive storage). Parameters:
​
map
Map
required
The map containing LocalAudiobook data (Map<String, dynamic>)
Returns: LocalAudiobook Note: Converts milliseconds back to DateTime and Duration objects. Sets default values for missing fields:
  • id: Empty string
  • title: Empty string
  • author: “Unknown”
  • folderPath: Empty string
  • audioFiles: Empty list
  • dateAdded: Epoch (January 1, 1970)
  • lastModified: Epoch (January 1, 1970)
Map<String, dynamic> map = {
  'id': 'local_123',
  'title': 'The Great Gatsby',
  'author': 'F. Scott Fitzgerald',
  'folderPath': '/storage/audiobooks/great_gatsby',
  'audioFiles': ['/storage/audiobooks/great_gatsby/chapter_01.mp3'],
  'totalDuration': 16200000, // milliseconds
  'dateAdded': 1640995200000, // milliseconds since epoch
  'lastModified': 1640995200000,
  'rating': 4.5
};

LocalAudiobook audiobook = LocalAudiobook.fromMap(map);

​
Usage Example

// Create a new local audiobook
LocalAudiobook audiobook = LocalAudiobook(
  id: DateTime.now().millisecondsSinceEpoch.toString(),
  title: "1984",
  author: "George Orwell",
  folderPath: "/storage/audiobooks/1984",
  audioFiles: [
    "/storage/audiobooks/1984/part1.mp3",
    "/storage/audiobooks/1984/part2.mp3",
    "/storage/audiobooks/1984/part3.mp3",
  ],
  dateAdded: DateTime.now(),
  lastModified: DateTime.now(),
  genre: "Dystopian Fiction",
);

// Save to Hive
Map<String, dynamic> audiobookMap = audiobook.toMap();
// await box.put(audiobook.id, audiobookMap);

// Retrieve from Hive
// Map<String, dynamic> retrievedMap = await box.get(id);
// LocalAudiobook retrievedBook = LocalAudiobook.fromMap(retrievedMap);

// Update the audiobook
LocalAudiobook ratedBook = audiobook.copyWith(
  rating: 4.8,
  lastModified: DateTime.now(),
);

print(ratedBook.formattedDuration); // "Unknown" if duration not set
print(ratedBook.hasCoverImage); // false

Build docs developers (and LLMs) love

Get started for freeTalk to us