LibriVox API Wrapper

A simple Dart wrapper for the LibriVox API that allows you to search and retrieve audiobook information from LibriVox.org.

Features

Search audiobooks by title, author, genre, or language
Get audiobook details by ID
Retrieve recent audiobooks
Built with Freezed for immutable data classes
Proper error handling with custom exceptions
Type-safe API responses

Getting started

Add this package to your pubspec.yaml:

dependencies:
  librivox: ^0.0.1

Usage

Basic Search

import 'package:librivox/librivox.dart';

void main() async {
  final librivox = LibriVoxWrapper();

  try {
    // Search by title
    final results = await librivox.searchAudiobooks(
      title: 'Sherlock Holmes',
      limit: 5,
    );

    for (final book in results.books) {
      print('${book.title} by ${book.author}');
    }
  } on LibriVoxException catch (e) {
    print('Error: ${e.message}');
  } finally {
    await librivox.close();
  }
}

Advanced Search

// Search with multiple parameters
final results = await librivox.searchAudiobooks(
  author: 'Mark Twain',
  language: 'English',
  genre: 'Fiction',
  limit: 10,
);

// Get recent audiobooks
final recent = await librivox.getRecentAudiobooks(limit: 5);

// Get specific book by ID
final book = await librivox.getAudiobookById(123);

Error Handling

try {
  final book = await librivox.getAudiobookById(999999);
} on LibriVoxException catch (e) {
  print('LibriVox Error: ${e.message}');
  if (e.statusCode != null) {
    print('HTTP Status: ${e.statusCode}');
  }
} catch (e) {
  print('Unexpected error: $e');
}

API Reference

LibriVoxWrapper

The main class for interacting with the LibriVox API.

Methods

searchAudiobooks({String? title, String? author, String? genre, String? language, int limit = 10}) - Search for audiobooks
getAudiobookById(int bookId) - Get a specific audiobook by ID
getRecentAudiobooks({int limit = 10}) - Get recent audiobooks
searchByKeyword(String keyword, {int limit = 10}) - Search by keyword
close() - Close the HTTP client

Data Models

LibriVoxBook

Represents an audiobook with the following properties:

id - Unique identifier
title - Book title
author - Author name
description - Book description
language - Language of the audiobook
copyrightYear - Copyright year
totalTime - Total duration
genre - Book genre
urlLibrivox - LibriVox URL
urlTextSource - Text source URL
dateReleased - Release date

SearchResult

Contains search results:

books - List of LibriVoxBook objects
totalCount - Total number of results

LibriVoxException

Custom exception for API errors:

message - Error message
statusCode - HTTP status code (optional)
details - Additional error details (optional)

Additional Information

This package uses the official LibriVox API (https://librivox.org/api/info) to fetch audiobook data. LibriVox is a collection of free public domain audiobooks read by volunteers.