LibriVox API #

A Dart package for accessing LibriVox audiobooks through the Internet Archive API. Search and retrieve free public domain audiobooks with ease.

Features #

✨ Simple API - Clean, intuitive interface for searching audiobooks
🔍 Powerful Search - Search by title with pagination support
📖 Detailed Metadata - Get comprehensive book information including descriptions and download links
🎧 Download Support - Direct access to audiobook files (ZIP, M4B formats)
🛡️ Error Handling - Comprehensive exception handling with specific error types
🚀 Lightweight - Minimal dependencies, maximum performance

Getting Started #

Add this package to your pubspec.yaml:

dependencies:
  librivox: ^0.0.1

Then run:

dart pub get

Usage #

Basic Search #

import 'package:librivox/librivox.dart';

void main() async {
  final api = LibrivoxApi();

  try {
    // Search for audiobooks
    final results = await api.searchTitles(
      query: 'Sherlock Holmes',
      rows: 10,
    );

    for (final book in results) {
      print('📚 ${book.title}');
      if (book.author != null) {
        print('✍️  by ${book.author}');
      }
      print('🔗 Cover: ${book.coverUrl}');
      print('---');
    }
  } on LibrivoxNotFoundException catch (e) {
    print('No results found: ${e.message}');
  } on LibrivoxApiException catch (e) {
    print('API Error: ${e.message}');
  }
}

Get Detailed Information #

// Get detailed information about a specific audiobook
final bookDetails = await api.getInfo('adventures_sherlock_holmes_0711_librivox');

print('Title: ${bookDetails.title}');
print('Author: ${bookDetails.author}');
print('Language: ${bookDetails.language}');
print('Release Date: ${bookDetails.releaseDate}');
print('Description: ${bookDetails.description}');

// Access download links
if (bookDetails.downloadLinks != null) {
  print('Download options:');
  for (final link in bookDetails.downloadLinks!) {
    print('  📥 $link');
  }
}

Advanced Search with Pagination #

// Search with pagination
final page1 = await api.searchTitles(
  query: 'Mark Twain',
  page: 1,
  rows: 5,
);

final page2 = await api.searchTitles(
  query: 'Mark Twain',
  page: 2,
  rows: 5,
);

Error Handling #

try {
  final book = await api.getInfo('nonexistent_book_id');
} on LibrivoxNotFoundException catch (e) {
  print('Book not found: ${e.message}');
} on LibrivoxParseException catch (e) {
  print('Failed to parse response: ${e.message}');
} on LibrivoxApiException catch (e) {
  print('API error: ${e.message}');
} catch (e) {
  print('Unexpected error: $e');
}

API Reference #

LibrivoxApi #

The main class for interacting with the LibriVox collection via Internet Archive.

Methods

searchTitles({required String query, int page = 1, int rows = 10})

Search for audiobooks by title.

Parameters:

• query (String, required): Search term for book titles
• page (int, optional): Page number for pagination (default: 1)
• rows (int, optional): Number of results per page (1-1000, default: 10)

Returns: Future<List<LibrivoxItem>>

Throws:

• ArgumentError: If query is empty, page < 1, or rows not in range 1-1000
• LibrivoxNotFoundException: If no results found
• LibrivoxApiException: If API request fails
• LibrivoxParseException: If response parsing fails

getInfo(String id)

Get detailed information about a specific audiobook.

Parameters:

• id (String, required): The Internet Archive identifier for the audiobook

Returns: Future<LibrivoxItem>

Throws:

• ArgumentError: If id is empty
• LibrivoxNotFoundException: If book not found
• LibrivoxApiException: If API request fails
• LibrivoxParseException: If response parsing fails

Data Models #

LibrivoxItem

Represents an audiobook with comprehensive metadata.

Properties:

• id (String): Unique Internet Archive identifier
• title (String): Book title
• author (String?): Author name (optional)
• releaseDate (String?): Release date (optional)
• description (String?): Book description (optional)
• language (String?): Language of the audiobook (optional)
• coverUrl (String?): URL to book cover image (optional)
• downloadLinks (List

Methods:

• fromJson(Map<String, dynamic> json): Create instance from JSON
• toJson(): Convert to JSON map
• copyWith({...}): Create copy with modified properties
• toString(): String representation

Exception Types #

All exceptions extend LibrivoxException with a descriptive message.

LibrivoxApiException

General API errors (network issues, HTTP errors)

LibrivoxNotFoundException

Thrown when requested content is not found

LibrivoxParseException

Thrown when response parsing fails

LibrivoxRateLimitException

Thrown when rate limits are exceeded

LibrivoxServerException

Thrown for server-side errors

Examples #

Search and Download #

import 'package:librivox/librivox.dart';

Future<void> findAndDownloadBook() async {
  final api = LibrivoxApi();
  
  // Search for a specific book
  final results = await api.searchTitles(
    query: 'Pride and Prejudice',
    rows: 1,
  );
  
  if (results.isNotEmpty) {
    // Get detailed info
    final book = await api.getInfo(results.first.id);
    
    print('Found: ${book.title} by ${book.author}');
    
    // Show available downloads
    if (book.downloadLinks?.isNotEmpty == true) {
      print('Available formats:');
      for (final link in book.downloadLinks!) {
        final format = link.split('.').last.toUpperCase();
        print('  $format: $link');
      }
    }
  }
}

Batch Processing #

Future<void> processMultipleBooks() async {
  final api = LibrivoxApi();
  final queries = ['Alice in Wonderland', 'Dracula', 'Frankenstein'];
  
  for (final query in queries) {
    try {
      final results = await api.searchTitles(query: query, rows: 1);
      if (results.isNotEmpty) {
        final book = await api.getInfo(results.first.id);
        print('✅ ${book.title} - ${book.downloadLinks?.length ?? 0} files');
      }
    } catch (e) {
      print('❌ Failed to process "$query": $e');
    }
  }
}

About LibriVox #

LibriVox is a non-commercial, non-profit project that provides free audiobooks from the public domain. All audiobooks are read by volunteers and are available for free download.

This package accesses LibriVox content through the Internet Archive API, which hosts the LibriVox collection.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License - see the LICENSE file for details.