Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart
46.8 KB
Raw Blame
import 'bookorbit_match.dart' show bookOrbitProviderIdFields;

/// Turns BookOrbit API payloads into the Audiobookshelf JSON shapes the rest
/// of the app reads. Pure functions only, so the shapes can be unit tested
/// without a server.
class BookOrbitMapper {
  BookOrbitMapper._();

  static const audioFormats = {'m4b', 'mp3', 'm4a', 'opus', 'ogg', 'flac'};
  static const ebookFormats = {
    'epub',
    'kepub',
    'pdf',
    'mobi',
    'azw3',
    'azw',
    'fb2',
    'djvu',
    'cbz',
    'cbr',
    'cb7',
  };

  /// Formats the app's reader can open, best first.
  static const _readerPreference = ['epub', 'kepub', 'pdf', 'cbz', 'cbr', 'cb7', 'mobi', 'azw3', 'azw', 'fb2'];

  static const _mimeTypes = {
    'm4b': 'audio/mp4',
    'm4a': 'audio/mp4',
    'mp3': 'audio/mpeg',
    'opus': 'audio/ogg',
    'ogg': 'audio/ogg',
    'flac': 'audio/flac',
  };

  /// Prefix for author ids the app made up from a name. Book cards only
  /// carry author names, so a tap on one resolves the real id later.
  static const authorNamePrefix = 'name:';

  static bool isAudioFormat(String? format) =>
      format != null && audioFormats.contains(format.toLowerCase());

  static bool _isContent(Map<String, dynamic> file) {
    final role = file['role'] as String?;
    return role == 'primary' || role == 'content';
  }

  static String? _format(Map<String, dynamic> file) =>
      (file['format'] as String?)?.toLowerCase();

  static int? ms(Object? iso) {
    if (iso is num) return iso.toInt();
    if (iso is! String || iso.isEmpty) return null;
    return DateTime.tryParse(iso)?.millisecondsSinceEpoch;
  }

  static String _str(Object? v) => v == null ? '' : '$v';

  static List<Map<String, dynamic>> _maps(Object? list) =>
      (list as List<dynamic>? ?? const []).whereType<Map<String, dynamic>>().toList();

  static List<String> _strings(Object? list) =>
      (list as List<dynamic>? ?? const []).map((e) => '$e').where((e) => e.isNotEmpty).toList();

  static String _lastFirst(String name) {
    final parts = name.trim().split(RegExp(r'\s+'));
    if (parts.length < 2) return name;
    final last = parts.removeLast();
    return '$last, ${parts.join(' ')}';
  }

  static Map<String, dynamic> library(Map<String, dynamic> lib) {
    final type = lib['type'] as String? ?? 'books';
    return {
      'id': _str(lib['id']),
      'name': lib['name'] ?? '',
      'displayOrder': lib['displayOrder'] ?? 0,
      'icon': 'database',
      'mediaType': type == 'podcasts' ? 'podcast' : 'book',
      'provider': 'audible',
      'folders': const [],
      'settings': {
        'coverAspectRatio': lib['coverAspectRatio'] == '1/1' ? 1 : 0,
      },
      'createdAt': ms(lib['createdAt']),
      'lastUpdate': ms(lib['updatedAt']),
      'bookCount': lib['bookCount'],
    };
  }

  static Map<String, dynamic> user(Map<String, dynamic> u) {
    final perms = _strings(u['permissions']);
    final superuser = u['isSuperuser'] == true || perms.contains('*');
    bool has(String p) => superuser || perms.contains(p);
    return {
      'id': _str(u['id']),
      'username': u['username'] ?? '',
      'email': u['email'],
      // Admin screens talk to Audiobookshelf-only endpoints, so everyone is
      // a plain user here until those screens learn BookOrbit.
      'type': 'user',
      'isActive': u['active'] != false,
      'isLocked': false,
      'permissions': {
        'download': has('library_download'),
        'update': has('library_edit_metadata'),
        'delete': has('library_delete_books'),
        'upload': false,
        'accessAllLibraries': true,
        'accessAllTags': true,
        'accessExplicitContent': true,
      },
      'librariesAccessible': const [],
      'itemTagsSelected': const [],
      'mediaProgress': const [],
      'bookmarks': const [],
      'seriesHideFromContinueListening': const [],
      'bookOrbit': {
        'name': u['name'],
        'isSuperuser': superuser,
        'permissions': perms,
        'provisioningMethod': u['provisioningMethod'],
        'timezone': (u['settings'] as Map?)?['timezone'],
      },
    };
  }

  static String trackContentUrl(String bookId, Object? fileId, String? assetId) {
    final asset = assetId == null ? '' : '?asset=$assetId';
    return '/api/items/$bookId/file/$fileId$asset';
  }

  /// Library item in the expanded Audiobookshelf shape. [detail] is a
  /// BookOrbit BookDetail, [card] a BookCard; either may be missing. With a
  /// [manifest] the tracks, chapters and duration come from it.
  static Map<String, dynamic> item({
    Map<String, dynamic>? card,
    Map<String, dynamic>? detail,
    Map<String, dynamic>? manifest,
    String? libraryId,
  }) {
    final src = detail ?? card ?? const <String, dynamic>{};
    final id = _str(src['id']);
    final files = _maps(src['files']);
    final contentFiles = files.where(_isContent).toList();

    final authorRefs = <Map<String, dynamic>>[];
    if (detail != null) {
      for (final a in _maps(detail['authors'])) {
        authorRefs.add({'id': _str(a['id']), 'name': a['name'] ?? ''});
      }
    } else {
      for (final name in _strings(src['authors'])) {
        authorRefs.add({'id': '$authorNamePrefix$name', 'name': name});
      }
    }
    final authorNames = authorRefs.map((a) => a['name'] as String).toList();

    final narratorNames = detail != null
        ? _maps((detail['audioMetadata'] as Map?)?['narrators'])
            .map((n) => '${n['name'] ?? ''}')
            .where((n) => n.isNotEmpty)
            .toList()
        : _strings(src['narrators']);

    final seriesList = <Map<String, dynamic>>[];
    final memberships = _maps(src['seriesMemberships']);
    if (memberships.isNotEmpty) {
      memberships.sort((a, b) =>
          ((a['displayOrder'] as num?) ?? 0).compareTo((b['displayOrder'] as num?) ?? 0));
      for (final m in memberships) {
        seriesList.add({
          'id': _str(m['seriesId']),
          'name': m['seriesName'] ?? '',
          'sequence': m['seriesIndex'],
        });
      }
    } else if (src['seriesName'] != null) {
      seriesList.add({
        'id': _str(src['seriesId'] ?? 'name:${src['seriesName']}'),
        'name': src['seriesName'],
        'sequence': src['seriesIndex'],
      });
    }
    final seriesName = seriesList
        .map((s) => s['sequence'] != null ? '${s['name']} #${s['sequence']}' : '${s['name']}')
        .join(', ');

    final title = (src['title'] as String?) ?? '';
    final providerIds = (detail?['providerIds'] as Map?) ?? const {};
    final audioMeta = detail?['audioMetadata'] as Map<String, dynamic>?;

    final metadata = <String, dynamic>{
      'title': title,
      'titleIgnorePrefix': title,
      'subtitle': src['subtitle'],
      'authors': authorRefs,
      'narrators': narratorNames,
      'series': seriesList,
      'genres': _strings(src['genres']),
      'publishedYear': src['publishedYear'] == null ? null : '${src['publishedYear']}',
      'publishedDate': src['publishedDate'],
      'publisher': src['publisher'],
      'description': detail?['description'],
      'isbn': detail?['isbn13'] ?? detail?['isbn10'] ?? src['isbn13'],
      'asin': providerIds['audible'] ?? providerIds['audnexus'],
      'language': src['language'],
      'explicit': false,
      'abridged': audioMeta?['abridged'] == true,
      'authorName': authorNames.join(', '),
      'authorNameLF': authorNames.map(_lastFirst).join(', '),
      'narratorName': narratorNames.join(', '),
      'seriesName': seriesName,
    };

    // Tracks: the manifest is the playback order; without one, fall back to
    // the file list (good enough to tell audio from ebook on a card).
    final audioFiles = <Map<String, dynamic>>[];
    final tracks = <Map<String, dynamic>>[];
    final assets = _maps(manifest?['assets']);
    final fileById = {for (final f in files) _str(f['id']): f};
    double offset = 0;
    if (assets.isNotEmpty) {
      for (var i = 0; i < assets.length; i++) {
        final a = assets[i];
        final fileId = _str(a['fileId']);
        final f = fileById[fileId] ?? const <String, dynamic>{};
        final fmt = ((a['format'] as String?) ?? _format(f) ?? 'mp3').toLowerCase();
        final dur = ((a['durationMs'] as num?) ?? 0) / 1000.0;
        final filename = (f['filename'] as String?) ?? 'track_${i + 1}.$fmt';
        final fileMeta = {
          'filename': filename,
          'ext': '.$fmt',
          'path': f['absolutePath'] ?? filename,
          'relPath': filename,
          'size': a['sizeBytes'] ?? f['sizeBytes'] ?? 0,
        };
        audioFiles.add({
          'index': i + 1,
          'ino': fileId,
          'metadata': fileMeta,
          'duration': dur,
          'mimeType': _mimeTypes[fmt] ?? 'audio/mpeg',
          'format': fmt,
          'assetId': a['assetId'],
        });
        tracks.add({
          'index': i + 1,
          'startOffset': offset,
          'duration': dur,
          'title': filename,
          'contentUrl': trackContentUrl(id, fileId, a['assetId'] as String?),
          'mimeType': _mimeTypes[fmt] ?? 'audio/mpeg',
          'metadata': fileMeta,
        });
        offset += dur;
      }
    } else {
      var i = 0;
      for (final f in contentFiles.where((f) => isAudioFormat(_format(f)))) {
        i++;
        final fmt = _format(f)!;
        final dur = ((f['durationSeconds'] as num?) ?? 0).toDouble();
        final filename = (f['filename'] as String?) ?? 'track_$i.$fmt';
        audioFiles.add({
          'index': i,
          'ino': _str(f['id']),
          'metadata': {
            'filename': filename,
            'ext': '.$fmt',
            'path': f['absolutePath'] ?? filename,
            'relPath': filename,
            'size': f['sizeBytes'] ?? 0,
          },
          'duration': dur,
          'mimeType': _mimeTypes[fmt] ?? 'audio/mpeg',
          'format': fmt,
        });
        offset += dur;
      }
    }

    final chapters = <Map<String, dynamic>>[];
    final manifestChapters = _maps(manifest?['chapters']);
    if (manifestChapters.isNotEmpty) {
      for (var i = 0; i < manifestChapters.length; i++) {
        final c = manifestChapters[i];
        chapters.add({
          'id': i,
          'start': ((c['startMs'] as num?) ?? 0) / 1000.0,
          'end': ((c['endMs'] as num?) ?? 0) / 1000.0,
          'title': c['title'] ?? 'Chapter ${i + 1}',
          'bookOrbitId': c['id'],
        });
      }
    } else {
      final raw = _maps(audioMeta?['chapters']);
      final total = _bookDurationSeconds(manifest, audioMeta, offset);
      for (var i = 0; i < raw.length; i++) {
        final start = ((raw[i]['startMs'] as num?) ?? 0) / 1000.0;
        final end = i + 1 < raw.length
            ? ((raw[i + 1]['startMs'] as num?) ?? 0) / 1000.0
            : total;
        chapters.add({'id': i, 'start': start, 'end': end, 'title': raw[i]['title'] ?? 'Chapter ${i + 1}'});
      }
    }

    // An EPUB 3 that reads itself aloud, with no audiobook beside it: its
    // narration is the book's audio, and the narrated copy is the one to read
    // so read along can follow it.
    final narrated = audioFiles.isEmpty ? narratedEpub(contentFiles) : null;
    final narrationSeconds =
        ((narrated?['mediaOverlay'] as Map?)?['durationSeconds'] as num?)?.toDouble() ?? 0;
    // A read along EPUB beside the audiobook it matches: the copy to read, so
    // read along follows its timings while the audiobook plays.
    final readAlong = audioFiles.isEmpty ? null : matchingReadAlong(detail, contentFiles);
    final ebook = narrated ?? readAlong?.file ?? _primaryEbook(contentFiles);
    final ebookFormat = ebook == null ? null : _format(ebook);
    final duration = narrated != null
        ? narrationSeconds
        : _bookDurationSeconds(manifest, audioMeta, offset);
    final size = files.fold<num>(0, (sum, f) => sum + ((f['sizeBytes'] as num?) ?? 0));
    final hasCover = detail != null
        ? detail['coverSource'] != null
        : src['hasCover'] == true;

    final media = <String, dynamic>{
      'id': id,
      'libraryItemId': id,
      'metadata': metadata,
      'coverPath': hasCover ? '/bookorbit/books/$id/cover' : null,
      'tags': _strings(src['tags']),
      'audioFiles': audioFiles,
      'chapters': chapters,
      'duration': duration,
      'size': size,
      'tracks': tracks,
      'ebookFile': ebook == null ? null : _ebookFileEntry(ebook),
      'ebookFormat': ebookFormat,
      if (narrated != null) 'narration': {'fileId': _str(narrated['id']), 'duration': narrationSeconds},
      if (readAlong != null)
        'readAlongEpub': {
          'fileId': _str(readAlong.file['id']),
          'duration': readAlong.narration,
          'audioDuration': readAlong.audio,
          if (_primaryEbook(contentFiles) case final plain? when plain != readAlong.file)
            'plainEbookFile': _ebookFileEntry(plain),
        },
      'numTracks': audioFiles.length,
      'numAudioFiles': audioFiles.length,
      'numChapters': chapters.length,
    };

    final item = <String, dynamic>{
      'id': id,
      'ino': id,
      'libraryId': _str(detail?['libraryId'] ?? libraryId),
      'folderId': '',
      'path': detail?['folderPath'] ?? '',
      'relPath': '',
      'isFile': false,
      'mediaType': 'book',
      'addedAt': ms(src['addedAt']),
      'updatedAt': ms(src['updatedAt']) ?? ms(src['addedAt']),
      'isMissing': src['status'] == 'missing',
      'isInvalid': false,
      'size': size,
      'numFiles': files.length,
      'media': media,
      'libraryFiles': const [],
      'bookOrbit': {
        'coverVersion': src['coverVersion'],
        'audioCover': _hasAudio(files),
        if (_hasReadAlong(files)) 'readAlong': true,
        'readStatus': src['readStatus'],
        'readingProgress': src['readingProgress'],
        if (detail != null) ...{
          'personalNote': detail['personalNote'],
          'communityRatings': detail['communityRatings'] ?? const [],
          'providerIds': detail['providerIds'] ?? const {},
          'files': [for (final f in files) _fileInfo(f)],
        },
      },
    };

    final collapsed = card?['collapsedSeries'] as Map<String, dynamic>?;
    if (collapsed != null && seriesList.isNotEmpty) {
      final seriesId = card?['seriesId'] != null ? _str(card!['seriesId']) : seriesList.first['id'];
      final seriesTitle = card?['seriesName'] ?? seriesList.first['name'];
      item['collapsedSeries'] = {
        'id': seriesId,
        'name': seriesTitle,
        'nameIgnorePrefix': seriesTitle,
        'numBooks': collapsed['bookCount'] ?? 0,
        'libraryItemIds': (collapsed['coverBookIds'] as List<dynamic>? ?? const [])
            .map((e) => '$e')
            .toList(),
        'seriesSequenceList': '',
      };
    }
    return item;
  }

  static const dockItemPrefix = 'dock-';

  /// A Book Dock file's metadata as it would be filed: what was saved for
  /// it, else what was read from the file (the server's own rule).
  static Map<String, dynamic> dockMetadata(Map<String, dynamic> file) {
    final m = file['selectedMetadata'] ?? file['embeddedMetadata'];
    return m is Map ? Map<String, dynamic>.from(m) : <String, dynamic>{};
  }

  /// A Book Dock file as an item of the 'book-dock' library. It has no
  /// tracks or ebook, so nothing tries to play, download or read it.
  static Map<String, dynamic> dockItem(Map<String, dynamic> file, {String libraryId = 'book-dock'}) {
    final fileId = _str(file['id']);
    final id = '$dockItemPrefix$fileId';
    final m = dockMetadata(file);
    final fileName = _str(file['fileName']);
    final dot = fileName.lastIndexOf('.');
    final stem = dot > 0 ? fileName.substring(0, dot) : fileName;
    final rawTitle = _str(m['title']).trim();
    final title = rawTitle.isNotEmpty ? rawTitle : stem;

    final authorNames = _strings(m['authors']);
    final narratorNames = _strings(m['narrators']);
    final seriesList = <Map<String, dynamic>>[];
    void addSeries(Object? name, Object? index) {
      final n = _str(name).trim();
      if (n.isEmpty) return;
      seriesList.add({'id': 'name:$n', 'name': n, 'sequence': index == null ? null : '$index'});
    }
    final memberships = _maps(m['seriesMemberships']);
    if (memberships.isNotEmpty) {
      for (final s in memberships) {
        addSeries(s['seriesName'], s['seriesIndex']);
      }
    } else {
      addSeries(m['seriesName'], m['seriesIndex']);
    }
    final seriesName = seriesList
        .map((s) => s['sequence'] != null ? '${s['name']} #${s['sequence']}' : '${s['name']}')
        .join(', ');
    final duration = ((m['durationSeconds'] as num?) ?? 0).toDouble();
    final size = (file['fileSize'] as num?) ?? 0;

    final metadata = <String, dynamic>{
      'title': title,
      'titleIgnorePrefix': title,
      'subtitle': m['subtitle'],
      'authors': [for (final a in authorNames) {'id': '$authorNamePrefix$a', 'name': a}],
      'narrators': narratorNames,
      'series': seriesList,
      'genres': _strings(m['genres']),
      'publishedYear': m['publishedYear'] == null ? null : '${m['publishedYear']}',
      'publishedDate': m['publishedDate'],
      'publisher': m['publisher'],
      'description': m['description'],
      'isbn': m['isbn13'] ?? m['isbn10'],
      'asin': m['audibleId'],
      'language': m['language'],
      'explicit': false,
      'abridged': m['abridged'] == true,
      'authorName': authorNames.join(', '),
      'authorNameLF': authorNames.map(_lastFirst).join(', '),
      'narratorName': narratorNames.join(', '),
      'seriesName': seriesName,
    };

    return {
      'id': id,
      'ino': id,
      'libraryId': libraryId,
      'folderId': '',
      'path': '',
      'relPath': '',
      'isFile': true,
      'mediaType': 'book',
      'addedAt': ms(file['createdAt']),
      'updatedAt': ms(file['updatedAt']) ?? ms(file['createdAt']),
      'isMissing': false,
      'isInvalid': false,
      'size': size,
      'numFiles': 1 + _maps(file['unitFiles']).length,
      'media': {
        'id': id,
        'libraryItemId': id,
        'metadata': metadata,
        'coverPath': '/bookorbit/dock/$fileId/cover',
        'tags': const [],
        'audioFiles': const [],
        'chapters': const [],
        'duration': duration,
        'size': size,
        'tracks': const [],
        'ebookFile': null,
        'numTracks': 0,
        'numAudioFiles': 0,
        'numChapters': 0,
      },
      'libraryFiles': const [],
      'bookDock': {
        'fileId': fileId,
        'status': file['status'],
        'fileName': fileName,
        'format': file['format'],
        'fileSize': file['fileSize'],
        'errorMessage': file['errorMessage'],
        'hasFoundDetails': _hasContent(file['fetchedMetadata']),
        'detailsState': _hasContent(file['selectedMetadata'])
            ? 'edited'
            : _hasContent(file['fetchedMetadata'])
                ? 'fetched'
                : _hasContent(file['embeddedMetadata'])
                    ? 'embedded'
                    : 'none',
        'confidence': (file['confidence'] as num?)?.round(),
        'targetLibraryId': file['targetLibraryId'] == null ? null : '${file['targetLibraryId']}',
        'targetFolderId': file['targetFolderId'] == null ? null : '${file['targetFolderId']}',
        'addedAt': ms(file['createdAt']),
        'unitFiles': [
          for (final u in _maps(file['unitFiles']))
            {'fileName': _str(u['fileName']), 'fileSize': u['fileSize'], 'role': u['role']},
        ],
        'changes': dockChanges(file),
        'providerIds': {
          for (final e in bookOrbitProviderIdFields.entries)
            if (e.key != 'audnexus' && _str(m[e.value]).trim().isNotEmpty) e.key: _str(m[e.value]).trim(),
        },
      },
    };
  }

  static bool _hasContent(Object? metadata) =>
      metadata is Map &&
      metadata.values.any((v) => v != null && v != '' && !(v is List && v.isEmpty));

  // The fields BookOrbit's web lists under "Proposed changes", in its order.
  static const _dockChangeFields = [
    'title',
    'subtitle',
    'authors',
    'seriesName',
    'publisher',
    'publishedYear',
    'language',
    'isbn13',
  ];

  /// What filing would change against what the file says about itself, the
  /// way BookOrbit's web shows it: the saved details, else the ones found
  /// online, field by field against the embedded ones. {field, from?, to}.
  static List<Map<String, dynamic>> dockChanges(Map<String, dynamic> file) {
    final incoming = file['selectedMetadata'] ?? file['fetchedMetadata'];
    if (incoming is! Map) return const [];
    final current = file['embeddedMetadata'] is Map ? file['embeddedMetadata'] as Map : const {};
    String? shown(Object? v) {
      if (v == null || v == '') return null;
      if (v is List) return v.isEmpty ? null : v.join(', ');
      return '$v';
    }
    return [
      for (final field in _dockChangeFields)
        if (shown(incoming[field]) != null && shown(incoming[field]) != shown(current[field]))
          {'field': field, 'from': shown(current[field]), 'to': shown(incoming[field])},
    ];
  }

  /// A dock file's metadata after an edit in the Audiobookshelf shape
  /// ([abs] is `body.metadata` of PATCH /items/:id/media). BookOrbit
  /// replaces a dock file's saved metadata whole, so this starts from
  /// [current] and only overwrites what the edit sent.
  static Map<String, dynamic> dockMetadataPatch(
    Map<String, dynamic> current,
    Map<String, dynamic> abs,
  ) {
    final out = Map<String, dynamic>.from(current);
    String? text(Object? v) {
      final s = v?.toString().trim() ?? '';
      return s.isEmpty ? null : s;
    }
    List<String> names(Object? list) => [
          for (final e in (list as List<dynamic>? ?? const []))
            if (text(e is Map ? e['name'] : e) != null) text(e is Map ? e['name'] : e)!,
        ];

    for (final key in ['title', 'subtitle', 'publisher', 'language']) {
      if (abs.containsKey(key)) out[key] = text(abs[key]);
    }
    if (abs.containsKey('description')) out['description'] = text(abs['description']) ?? '';
    if (abs.containsKey('publishedDate')) {
      final d = text(abs['publishedDate']);
      out['publishedDate'] = d != null && RegExp(r'^\d{4}-\d{2}-\d{2}$').hasMatch(d) ? d : null;
    }
    if (abs.containsKey('publishedYear')) {
      // A full date (from a match) sets the date and its year.
      final v = text(abs['publishedYear']) ?? '';
      if (RegExp(r'^\d{4}-\d{2}-\d{2}$').hasMatch(v)) out['publishedDate'] = v;
      final y = int.tryParse(RegExp(r'^\d{4}').firstMatch(v)?.group(0) ?? '');
      out['publishedYear'] = y != null && y >= 1000 && y <= 2200 ? y : null;
    }
    if (abs.containsKey('authors')) out['authors'] = names(abs['authors']);
    if (abs.containsKey('narrators')) out['narrators'] = names(abs['narrators']);
    if (abs.containsKey('genres')) out['genres'] = names(abs['genres']);
    if (abs.containsKey('series')) {
      final series = [
        for (final s in (abs['series'] as List<dynamic>? ?? const []).whereType<Map>())
          if (text(s['name']) != null)
            {'seriesName': text(s['name']), 'seriesIndex': text(s['sequence'])},
      ];
      out['seriesMemberships'] = series;
      out['seriesName'] = series.isEmpty ? null : series.first['seriesName'];
      out['seriesIndex'] = series.isEmpty ? null : series.first['seriesIndex'];
    }
    if (abs.containsKey('isbn')) {
      final isbn = text(abs['isbn'])?.replaceAll(RegExp(r'[^0-9Xx]'), '');
      out['isbn13'] = isbn != null && isbn.length == 13 ? isbn : null;
      out['isbn10'] = isbn != null && isbn.length == 10 ? isbn : null;
    }
    if (abs.containsKey('asin')) out['audibleId'] = text(abs['asin']);
    if (abs.containsKey('abridged')) out['abridged'] = abs['abridged'] == true;
    out.addAll(providerIdPatch(abs['bookOrbitProviderIds']));
    return out;
  }

  /// [found] (what the server looked up online) laid over [current],
  /// field by field, keeping [current] where [found] has nothing.
  static Map<String, dynamic> dockMergeFound(
    Map<String, dynamic> current,
    Map<String, dynamic> found,
  ) {
    final out = Map<String, dynamic>.from(current);
    found.forEach((key, value) {
      final empty = value == null ||
          (value is String && value.trim().isEmpty) ||
          (value is List && value.isEmpty);
      if (!empty) out[key] = value;
    });
    return out;
  }

  static bool _hasAudio(List<Map<String, dynamic>> files) =>
      files.where(_isContent).any((f) => isAudioFormat(_format(f)));

  /// An EPUB that reads itself aloud, which BookOrbit's covers mark with
  /// headphones. Its length can still be unknown.
  static bool _hasReadAlong(List<Map<String, dynamic>> files) => files.where(_isContent).any(
      (f) => _format(f) == 'epub' && (f['mediaOverlay'] as Map?)?['available'] == true);

  /// One of a book's files as the file info sheet shows it.
  static Map<String, dynamic> _fileInfo(Map<String, dynamic> f) {
    final path = f['absolutePath'] as String?;
    return {
      'id': _str(f['id']),
      'filename': f['filename'] ?? path?.split(RegExp(r'[\\/]')).last,
      'format': _format(f),
      'role': f['role'],
      'size': f['sizeBytes'],
      'duration': f['durationSeconds'],
      'path': path,
      'readAlong': _format(f) == 'epub' && (f['mediaOverlay'] as Map?)?['available'] == true,
    };
  }

  /// An EPUB carrying its own narration (EPUB 3 media overlays) of a known
  /// length, or null.
  static Map<String, dynamic>? narratedEpub(List<Map<String, dynamic>> contentFiles) {
    for (final f in contentFiles) {
      if (_format(f) != 'epub') continue;
      final overlay = f['mediaOverlay'] as Map?;
      if (overlay?['available'] == true && ((overlay?['durationSeconds'] as num?) ?? 0) > 0) return f;
    }
    return null;
  }

  static Map<String, dynamic> _ebookFileEntry(Map<String, dynamic> f) {
    final format = _format(f);
    return {
      'ino': _str(f['id']),
      'ebookFormat': format,
      if ((f['fileHash'] ?? f['contentVersion']) != null) 'version': '${f['fileHash'] ?? f['contentVersion']}',
      'metadata': {
        'filename': f['filename'] ?? 'book.$format',
        'ext': '.$format',
        'size': f['sizeBytes'] ?? 0,
      },
    };
  }

  /// The read along EPUB BookOrbit keeps in step with the audiobook: its
  /// Read-aloud progress sync is on and the two lengths agree. Only a book's
  /// full details say so.
  static ({Map<String, dynamic> file, double narration, double audio})? matchingReadAlong(
    Map<String, dynamic>? detail,
    List<Map<String, dynamic>> contentFiles,
  ) {
    final sync = detail?['readAloudSync'];
    if (sync is! Map || sync['state'] != 'enabled') return null;
    final narration = (sync['overlayDurationSeconds'] as num?)?.toDouble() ?? 0;
    final audio = (sync['audioDurationSeconds'] as num?)?.toDouble() ?? 0;
    if (narration <= 0 || audio <= 0) return null;
    for (final f in contentFiles) {
      if (_str(f['id']) != _str(sync['overlayFileId']) || _format(f) != 'epub') continue;
      if ((f['mediaOverlay'] as Map?)?['available'] != true) return null;
      return (file: f, narration: narration, audio: audio);
    }
    return null;
  }

  static Map<String, dynamic>? _primaryEbook(List<Map<String, dynamic>> contentFiles) {
    final ebooks = contentFiles.where((f) {
      final fmt = _format(f);
      return fmt != null && ebookFormats.contains(fmt);
    }).toList();
    if (ebooks.isEmpty) return null;
    bool narrated(Map<String, dynamic> f) => (f['mediaOverlay'] as Map?)?['available'] == true;
    for (final fmt in _readerPreference) {
      Map<String, dynamic>? fallback;
      for (final f in ebooks) {
        if (_format(f) != fmt) continue;
        if (!narrated(f)) return f;
        fallback ??= f;
      }
      if (fallback != null) return fallback;
    }
    return ebooks.first;
  }

  static double _bookDurationSeconds(
    Map<String, dynamic>? manifest,
    Map<String, dynamic>? audioMeta,
    double trackSum,
  ) {
    final total = manifest?['totalDurationMs'] as num?;
    if (total != null && total > 0) return total / 1000.0;
    if (trackSum > 0) return trackSum;
    final meta = audioMeta?['durationSeconds'] as num?;
    return meta?.toDouble() ?? 0;
  }

  /// Book-absolute seconds for a track-local playback state.
  static double absolutePosition(Map<String, dynamic> manifest, Map<String, dynamic> state) {
    final assetId = state['assetId'];
    final local = ((state['positionMs'] as num?) ?? 0) / 1000.0;
    double elapsed = 0;
    for (final a in _maps(manifest['assets'])) {
      if (a['assetId'] == assetId) return elapsed + local;
      elapsed += ((a['durationMs'] as num?) ?? 0) / 1000.0;
    }
    return local;
  }

  /// The asset and track-local milliseconds for a book-absolute position.
  static ({String assetId, int positionMs})? trackPosition(
    Map<String, dynamic> manifest,
    double absoluteSeconds,
  ) {
    final assets = _maps(manifest['assets']);
    if (assets.isEmpty) return null;
    var remainingMs = (absoluteSeconds * 1000).round();
    if (remainingMs < 0) remainingMs = 0;
    for (var i = 0; i < assets.length; i++) {
      final a = assets[i];
      final dur = (a['durationMs'] as num?)?.toInt();
      final last = i == assets.length - 1;
      if (dur == null || last || remainingMs < dur) {
        final pos = dur != null && remainingMs > dur ? dur : remainingMs;
        return (assetId: a['assetId'] as String, positionMs: pos);
      }
      remainingMs -= dur;
    }
    return null;
  }

  static double totalSeconds(Map<String, dynamic> manifest) =>
      ((manifest['totalDurationMs'] as num?) ?? 0) / 1000.0;

  static bool _finishedStatus(Map<String, dynamic>? readStatus) {
    final s = readStatus?['status'];
    return s == 'read' || s == 'skimmed';
  }

  /// Audiobookshelf media progress for a book. [state] is the audiobook
  /// playback state (may be null), [readStatus] the book's UserBookStatus.
  static Map<String, dynamic> progress({
    required String bookId,
    Map<String, dynamic>? manifest,
    Map<String, dynamic>? state,
    Map<String, dynamic>? readStatus,
    double? ebookPercent,
    String? ebookLocation,
    int? ebookUpdatedAt,
  }) {
    final duration = manifest != null ? totalSeconds(manifest) : 0.0;
    final current = manifest != null && state != null ? absolutePosition(manifest, state) : 0.0;
    final pct = ((state?['percentage'] as num?) ?? 0).toDouble();
    final finished = _finishedStatus(readStatus) || state?['completed'] == true;
    final stateUpdated = ms(state?['capturedAt']) ?? 0;
    final statusUpdated = ms(readStatus?['updatedAt']) ?? 0;
    final lastUpdate = [stateUpdated, statusUpdated, ebookUpdatedAt ?? 0].reduce((a, b) => a > b ? a : b);
    return {
      'id': 'bo-$bookId',
      'libraryItemId': bookId,
      'episodeId': null,
      'mediaItemId': bookId,
      'mediaItemType': 'book',
      'duration': duration,
      'progress': finished ? 1.0 : (pct / 100.0).clamp(0.0, 1.0),
      'currentTime': current,
      'isFinished': finished,
      'skimmed': readStatus?['status'] == 'skimmed',
      'hideFromContinueListening': false,
      'ebookLocation': ebookLocation,
      'ebookProgress': ebookPercent == null ? null : (ebookPercent / 100.0).clamp(0.0, 1.0),
      'lastUpdate': lastUpdate,
      'startedAt': ms(readStatus?['startedAt']) ?? stateUpdated,
      'finishedAt': finished ? ms(readStatus?['finishedAt']) : null,
      'bookOrbitRevision': state?['revision'],
    };
  }

  /// Progress built from a book card alone, for list-level sync. It carries
  /// the percent and finished flag but no position, so callers must not
  /// treat its currentTime as a place to resume from.
  static Map<String, dynamic> cardProgress(Map<String, dynamic> card) {
    final id = _str(card['id']);
    final readStatus = card['readStatus'] as Map<String, dynamic>?;
    final finished = _finishedStatus(readStatus);
    final pct = ((card['readingProgress'] as num?) ?? 0).toDouble();
    return {
      'id': 'bo-$id',
      'libraryItemId': id,
      'episodeId': null,
      'mediaItemId': id,
      'mediaItemType': 'book',
      'duration': 0,
      'progress': finished ? 1.0 : (pct / 100.0).clamp(0.0, 1.0),
      'currentTime': 0,
      'isFinished': finished,
      'skimmed': readStatus?['status'] == 'skimmed',
      'hideFromContinueListening': false,
      'lastUpdate': ms(readStatus?['updatedAt']) ?? 0,
      'startedAt': ms(readStatus?['startedAt']),
      'finishedAt': finished ? ms(readStatus?['finishedAt']) : null,
      'positionUnknown': true,
    };
  }

  static Map<String, dynamic> bookmark(Map<String, dynamic> b) => {
        'libraryItemId': _str(b['bookId']),
        'title': b['title'] ?? '',
        'time': ((b['positionMs'] as num?) ?? 0) / 1000.0,
        'createdAt': ms(b['createdAt']) ?? 0,
        'bookOrbitId': b['id'],
        'note': b['note'],
      };

  static Map<String, dynamic> series(Map<String, dynamic> s, {List<Map<String, dynamic>> books = const []}) {
    final coverIds = (s['coverBookIds'] as List<dynamic>? ?? const []).map((e) => '$e').toList();
    return {
      'id': _str(s['id']),
      'name': s['name'] ?? '',
      'nameIgnorePrefix': s['name'] ?? '',
      'type': 'series',
      'numBooks': s['bookCount'] ?? books.length,
      'addedAt': ms(s['lastAddedAt']),
      'updatedAt': ms(s['lastAddedAt']),
      'books': books,
      'coverBookIds': coverIds,
      'authors': _strings(s['authors']),
    };
  }

  static Map<String, dynamic> author(Map<String, dynamic> a) => {
        'id': _str(a['id']),
        'name': a['name'] ?? '',
        'description': a['description'],
        'imagePath': a['imageUrl'],
        'numBooks': a['bookCount'] ?? 0,
        'addedAt': ms(a['lastAddedAt']),
        // The image URL carries the file's time, so a new image busts caches.
        'updatedAt': int.tryParse(Uri.tryParse('${a['imageUrl'] ?? ''}')?.queryParameters['t'] ?? '') ??
            ms(a['lastAddedAt']),
        'bookOrbit': {
          'imageUrl': a['imageUrl'],
          'coverBookId': a['coverBookId'],
          'sortName': a['sortName'],
        },
      };

  /// Metadata providers in the order, colors and wording of BookOrbit's web
  /// book page.
  static const _providerOrder = [
    'google',
    'goodreads',
    'amazon',
    'hardcover',
    'openLibrary',
    'itunes',
    'audible',
    'librofm',
    'kobo',
    'comicvine',
    'ranobedb',
    'lubimyczytac',
    'aladin',
  ];

  static const providerColors = {
    'google': 0xFF34A853,
    'goodreads': 0xFF00D8D1,
    'amazon': 0xFFFF9900,
    'hardcover': 0xFF7772FF,
    'openLibrary': 0xFF49A4FF,
    'itunes': 0xFFFF4F5D,
    'audible': 0xFFFF8A00,
    'librofm': 0xFF62B9B6,
    'comicvine': 0xFFFFDB0F,
    'ranobedb': 0xFFA78CFF,
    'kobo': 0xFFE23434,
    'lubimyczytac': 0xFFF47373,
    'aladin': 0xFF3E7FFF,
  };

  static const _providerLabels = {
    'google': 'Google Books',
    'goodreads': 'Goodreads',
    'amazon': 'Amazon',
    'hardcover': 'Hardcover',
    'openLibrary': 'Open Library',
    'itunes': 'Apple Books',
    'audible': 'Audible',
    'librofm': 'Libro.fm',
    'kobo': 'Kobo',
    'comicvine': 'ComicVine',
    'ranobedb': 'RanobeDB',
    'lubimyczytac': 'LubimyCzytac',
    'aladin': 'Aladin',
  };

  /// Icon file names under the server's `/assets/provider-icons/`.
  static const _providerIcons = {
    'google': 'google.svg',
    'goodreads': 'goodreads.svg',
    'amazon': 'amazon.svg',
    'hardcover': 'hardcover.svg',
    'openLibrary': 'openlibrary.svg',
    'itunes': 'apple-books.svg',
    'audible': 'audible.svg',
    'librofm': 'librofm.svg',
    'kobo': 'kobo.svg',
    'ranobedb': 'ranobedb.svg',
    'lubimyczytac': 'lubimyczytac.svg',
    'aladin': 'aladin.svg',
  };

  static const _providerMarks = {
    'google': 'G',
    'goodreads': 'GR',
    'amazon': 'A',
    'hardcover': 'H',
    'openLibrary': 'OL',
    'itunes': 'AB',
    'audible': 'Au',
    'librofm': 'Lf',
    'kobo': 'K',
    'comicvine': 'CV',
    'ranobedb': 'RN',
    'lubimyczytac': 'LC',
    'aladin': 'Al',
  };

  /// The book's page on a provider's site, as the web app links it.
  static String? providerUrl(String key, String id) {
    final e = Uri.encodeComponent(id);
    return switch (key) {
      'google' => 'https://books.google.com/books?id=$e',
      'goodreads' => 'https://www.goodreads.com/book/show/$e',
      'amazon' => 'https://www.amazon.com/dp/$e',
      'hardcover' => 'https://hardcover.app/books/$e',
      'openLibrary' =>
        'https://openlibrary.org/works/${Uri.encodeComponent(id.startsWith('/works/') ? id.substring(7) : id)}',
      'itunes' => 'https://books.apple.com/book/id$e',
      'audible' => 'https://www.audible.com/pd/$e',
      'librofm' => 'https://libro.fm/audiobooks/$e',
      'kobo' => 'https://www.kobo.com/us/en/ebook/$e',
      'comicvine' => 'https://comicvine.gamespot.com/issue/4000-$e/',
      'ranobedb' => 'https://ranobedb.org/book/$e',
      'lubimyczytac' =>
        'https://lubimyczytac.pl/ksiazka/${(id.contains('/') ? id : '$id/-').split('/').map(Uri.encodeComponent).join('/')}',
      'aladin' => 'https://www.aladin.co.kr/shop/wproduct.aspx?ItemId=$e',
      _ => null,
    };
  }

  /// A badge for [key] with no link or rating yet.
  static Map<String, dynamic> providerBadge(String key) => {
        'key': key,
        'label': _providerLabels[key] ?? key,
        'url': null,
        'icon': _providerIcons[key],
        'mark': _providerMarks[key] ?? (key.length > 2 ? key.substring(0, 2) : key).toUpperCase(),
        'color': providerColors[key] ?? 0xFF7A7A7A,
      };

  /// One badge per provider the book links to or has a rating from, in the
  /// web app's order: {key, label, url, icon, mark, color, rating?, count?}.
  static List<Map<String, dynamic>> providerBadges(Map? providerIds, List? ratings) {
    final ids = <String, String>{
      for (final e in (providerIds ?? const {}).entries)
        if (e.value is String && (e.value as String).trim().isNotEmpty) '${e.key}': (e.value as String).trim(),
    };
    final rated = <String, Map>{};
    for (final r in (ratings ?? const []).whereType<Map>()) {
      final value = r['rating'];
      if (value is! num || !value.isFinite || value <= 0) continue;
      final key = r['provider'] == 'audnexus' ? 'audible' : '${r['provider']}';
      rated.putIfAbsent(key, () => r);
    }
    final keys = [
      ..._providerOrder.where((k) => ids.containsKey(k) || rated.containsKey(k)),
      ...rated.keys.where((k) => !_providerOrder.contains(k)),
    ];
    return [
      for (final k in keys)
        {
          ...providerBadge(k),
          'url': ids[k] == null ? null : providerUrl(k, ids[k]!),
          if (rated[k] != null) ...{
            'rating': (rated[k]!['rating'] as num).toDouble(),
            'count': (rated[k]!['ratingCount'] as num?)?.toInt(),
          },
        },
    ];
  }

  /// A BookOrbit "more like this" pick, trimmed to what a cover row shows.
  static Map<String, dynamic> similarBook(Map<String, dynamic> r) {
    final status = (r['readStatus'] as Map?)?['status'];
    return {
      'id': _str(r['id']),
      'title': r['title'] ?? '',
      'authorName': _strings(r['authors']).join(', '),
      'hasCover': r['hasCover'] == true,
      'isAudiobook': r['isAudiobook'] == true,
      'finished': status == 'read' || status == 'skimmed',
    };
  }

  static String? _text(Object? v) {
    final s = v?.toString().trim() ?? '';
    return s.isEmpty ? null : s;
  }

  static List<String> _names(Object? list) => (list as List<dynamic>? ?? const [])
      .map((e) => e is Map ? _text(e['name'] ?? e['series']) : _text(e))
      .whereType<String>()
      .toList();

  static bool _sameList(List<Object?> a, List<Object?> b) {
    if (a.length != b.length) return false;
    for (var i = 0; i < a.length; i++) {
      if (a[i] != b[i]) return false;
    }
    return true;
  }

  static final _seriesIndexPattern = RegExp(r'^\d+(?:\.\d+)?$');

  /// BookOrbit only takes plain numbers ("2", "2.5") as a series index.
  static String? seriesIndex(Object? raw) {
    final s = _text(raw);
    if (s == null) return null;
    if (_seriesIndexPattern.hasMatch(s)) return s;
    final m = RegExp(r'\d+(?:\.\d+)?').firstMatch(s);
    return m?.group(0);
  }

  /// The BookOrbit metadata PATCH for an Audiobookshelf media update, holding
  /// only the fields that differ from [current] (the item as the app shows
  /// it). Untouched fields stay out so a locked field the user did not change
  /// can't make BookOrbit refuse the whole save.
  static Map<String, dynamic> metadataPatch({
    required Map<String, dynamic> metadata,
    List<String>? tags,
    required Map<String, dynamic> current,
    required bool hasAudio,
  }) {
    final cur = (current['metadata'] as Map?)?.cast<String, dynamic>() ?? const <String, dynamic>{};
    final out = <String, dynamic>{};
    final audio = <String, dynamic>{};

    void text(String key, String boKey, int? max) {
      if (!metadata.containsKey(key)) return;
      final next = _text(metadata[key]);
      if (next == _text(cur[key])) return;
      out[boKey] = next != null && max != null && next.length > max ? next.substring(0, max) : next;
    }

    text('title', 'title', 1000);
    text('subtitle', 'subtitle', 1000);
    text('description', 'description', null);
    text('publisher', 'publisher', 500);
    text('language', 'language', 100);

    if (metadata.containsKey('publishedYear')) {
      final next = _text(metadata['publishedYear']);
      if (next != _text(cur['publishedYear'])) {
        if (next == null) {
          out['publishedYear'] = null;
        } else if (RegExp(r'^\d{4}-\d{2}-\d{2}$').hasMatch(next)) {
          out['publishedDate'] = next;
        } else {
          final year = int.tryParse(RegExp(r'\d{4}').firstMatch(next)?.group(0) ?? '');
          if (year != null && year >= 1000 && year <= 2200) out['publishedYear'] = year;
        }
      }
    }

    if (metadata.containsKey('asin')) {
      final next = _text(metadata['asin']);
      if (next != _text(cur['asin']) && (next == null || next.length <= 20)) out['audibleId'] = next;
    }

    if (metadata.containsKey('isbn')) {
      final next = _text(metadata['isbn']);
      if (next != _text(cur['isbn'])) {
        final plain = next?.replaceAll(RegExp(r'[\s-]'), '');
        if (plain == null) {
          out['isbn13'] = null;
          out['isbn10'] = null;
        } else if (plain.length == 10) {
          // The app shows the 13-digit one first, so drop it or the edit
          // would look like it never saved.
          out['isbn10'] = plain;
          out['isbn13'] = null;
        } else if (plain.length <= 13) {
          out['isbn13'] = plain;
        }
      }
    }

    if (metadata.containsKey('authors')) {
      final next = _names(metadata['authors']);
      if (!_sameList(next, _names(cur['authors']))) out['authors'] = next;
    }

    if (metadata.containsKey('genres')) {
      final next = _names(metadata['genres']);
      if (!_sameList(next, _names(cur['genres']))) out['genres'] = next;
    }

    if (tags != null) {
      final next = tags.map(_text).whereType<String>().toList();
      if (!_sameList(next, _names(current['tags']))) out['tags'] = next;
    }

    if (metadata.containsKey('series')) {
      final next = <({String name, String? index})>[];
      for (final s in (metadata['series'] as List<dynamic>? ?? const []).whereType<Map>()) {
        final name = _text(s['name'] ?? s['series']);
        if (name == null) continue;
        next.add((name: name.length > 500 ? name.substring(0, 500) : name, index: seriesIndex(s['sequence'])));
      }
      final now = [
        for (final s in (cur['series'] as List<dynamic>? ?? const []).whereType<Map>())
          (name: _text(s['name']) ?? '', index: seriesIndex(s['sequence'])),
      ];
      if (!_sameList(next, now)) {
        out['seriesMemberships'] = next.isEmpty
            ? null
            : [for (final s in next) {'seriesName': s.name, 'seriesIndex': s.index}];
      }
    }

    if (hasAudio) {
      if (metadata.containsKey('narrators')) {
        final next = _names(metadata['narrators']);
        if (!_sameList(next, _names(cur['narrators']))) audio['narrators'] = next;
      }
      if (metadata.containsKey('abridged')) {
        final next = metadata['abridged'] == true;
        if (next != (cur['abridged'] == true)) audio['abridged'] = next;
      }
    }
    if (audio.isNotEmpty) out['audioMetadata'] = audio;
    out.addAll(providerIdPatch(metadata['bookOrbitProviderIds']));
    return out;
  }

  /// `{goodreads: '123'}` from a match as BookOrbit's flat id fields
  /// (`goodreadsId: '123'`).
  static Map<String, String> providerIdPatch(Object? ids) => {
        if (ids is Map)
          for (final e in ids.entries)
            if (bookOrbitProviderIdFields['${e.key}'] != null && '${e.value}'.trim().isNotEmpty)
              bookOrbitProviderIdFields['${e.key}']!: '${e.value}'.trim(),
      };

  /// Chapters saved on a book's audio details, where the chapter editor
  /// writes them, laid out to [duration]. Empty when none are saved.
  static List<Map<String, dynamic>> savedChapters(Map<String, dynamic> detail, double duration) {
    final raw = _maps((detail['audioMetadata'] as Map?)?['chapters']);
    double start(int i) => ((raw[i]['startMs'] as num?) ?? 0) / 1000.0;
    return [
      for (var i = 0; i < raw.length; i++)
        {
          'id': i,
          'start': start(i),
          'end': i + 1 < raw.length ? start(i + 1) : duration,
          'title': raw[i]['title'] ?? 'Chapter ${i + 1}',
        },
    ];
  }

  /// Audiobookshelf chapters ({start, end, title} in seconds) as BookOrbit's
  /// audio chapters. Null clears them.
  static List<Map<String, dynamic>>? chapters(List<dynamic> abs) {
    final rows = abs.whereType<Map>().toList()
      ..sort((a, b) => ((a['start'] as num?) ?? 0).compareTo((b['start'] as num?) ?? 0));
    if (rows.isEmpty) return null;
    return [
      for (var i = 0; i < rows.length; i++)
        {
          'title': _text(rows[i]['title']) ?? 'Chapter ${i + 1}',
          'startMs': (((rows[i]['start'] as num?) ?? 0) * 1000).round(),
          if (rows[i]['end'] is num && (rows[i]['end'] as num) > ((rows[i]['start'] as num?) ?? 0))
            'durationMs': ((((rows[i]['end'] as num) - ((rows[i]['start'] as num?) ?? 0))) * 1000).round(),
        },
    ];
  }

  /// A BookOrbit metadata candidate in the shape Audiobookshelf's book
  /// search returns.
  static Map<String, dynamic> searchResult(Map<String, dynamic> c) {
    final memberships = _maps(c['seriesMemberships']);
    final year = c['publishedYear'] ??
        RegExp(r'^\d{4}').firstMatch('${c['publishedDate'] ?? ''}')?.group(0);
    final authors = _strings(c['authors']);
    final narrators = _strings(c['narrators']);
    return {
      'title': c['displayTitle'] ?? c['title'],
      'subtitle': c['subtitle'],
      'author': authors.isEmpty ? null : authors.join(', '),
      'narrator': narrators.isEmpty ? null : narrators.join(', '),
      'description': c['description'],
      'publisher': c['publisher'],
      'publishedYear': year?.toString(),
      'asin': c['audibleId'] ?? (c['provider'] == 'audible' ? c['providerId'] : null),
      'isbn': c['isbn13'] ?? c['isbn10'],
      'language': c['language'],
      'genres': _strings(c['genres']),
      'series': memberships.isNotEmpty
          ? [for (final m in memberships) {'name': m['seriesName'], 'sequence': m['seriesIndex']}]
          : c['seriesName'],
      'sequence': c['seriesIndex'],
      'cover': c['coverUrl'],
      'duration': c['durationSeconds'],
      'provider': c['provider'],
    };
  }
}