GitHub - ef1500/libbbf: Bound Book Format: A high-performance, DirectStorage-native container format for comics and manga

Skip to content

Navigation Menu

Toggle navigation

Sign in

Appearance settings

PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

ef1500

/

libbbf

Public

Notifications
You must be signed in to change notification settings

Fork
2

Star
193

Bound Book Format: A high-performance, DirectStorage-native container format for comics and manga

License

MIT license

193
stars

2
forks

Branches

Tags

Activity

Star

Notifications
You must be signed in to change notification settings

Code

Issues
2

Pull requests
0

Actions

Projects
0

Security

Uh oh!

There was an error while loading. Please reload this page.

Insights

Additional navigation options

Code

Issues

Pull requests

Actions

Projects

Security

Insights

ef1500/libbbf

 mainBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History33 Commits.github/workflows.github/workflows  srcsrc  .gitignore.gitignore  CMakeLists.txtCMakeLists.txt  LICENSELICENSE  readme.mdreadme.md  View all filesRepository files navigationREADMEMIT licenselibbbf: Bound Book Format

WarningOfficial Source Notice: Please only download releases from this repository (ef1500/libbbf). External mirrors or forks may contain malware.

Bound Book Format (.bbf) is a high-performance binary container designed specifically for digital comic books and manga. Unlike CBR/CBZ, BBF is built for DirectSotrage/mmap, easy integrity checks, and mixed-codec containerization.

Getting Started
Prerequisites

C++17 compliant compiler (GCC/Clang/MSVC), and optionally CMake
xxHash library

Compilation
CMake
cmake -B build
cmake --build build
sudo cmake --install build
Manual
Linux
g++ -std=c++17 bbfenc.cpp libbbf.cpp xxhash.c -o bbfmux -pthread
Windows
g++ -std=c++17 bbfenc.cpp libbbf.cpp xxhash.c -o bbfmux -municode
Alternatively, if you need python support, use libbbf-python.

Technical Details
BBF is designed as a Footer-indexed binary format. This allows for rapid append-only creation and immediate random access to any page without scanning the entire file.
MMAP Compatibility
The bbfmux reference implementation utilizes Memory Mapping (mmap/MapViewOfFile). Instead of reading file data into intermediate buffers, the tool maps the container directly into the process address space. This allows the CPU to access image data at the speed of your NVMe drive's hardware limit.
High-Speed Parallel Verification
Integrity checks utilize Parallel XXH3. On multi-core systems, the verifier splits the asset table into chunks and validates multiple pages simultaneously. This makes BBF verification up to 10x faster than ZIP/RAR CRC checks.
4KB Alignment
Every asset in a BBF file starts on a 4096-byte boundary. This alignment is critical for modern hardware, allowing for DirectStorage transfers directly from disk to GPU memory, bypassing CPU bottlenecks entirely.
Note: DirectStorage isn't avaliable for images yet (as far as I know), but I've made sure to accomodate such a thing in the future with this format.
Binary Layout

Header (13 bytes): Magic BBF1, versioning, and initial padding.
Page Data: The raw image payloads (AVIF, PNG, etc.), each padded to 4096-byte boundaries.
String Pool: A deduplicated pool of null-terminated strings for metadata and section titles.
Asset Table: A registry of physical data blobs with XXH3 hashes.
Page Table: The logical reading order, mapping logical pages to assets.
Section Table: Markers for chapters, volumes, or gallery sections.
Metadata Table: Key-Value pairs for archival data (Author, Scanlation team, etc.).
Footer (76 bytes): Table offsets and a final integrity hash.

NOTE: libbbf.h includes a flags field, as well as extra padding for each asset entry. This is so that in the future libbbf can accomodate future technical advancements in both readers and image storage. I.E. If images support DirectStorage in the future, then BBF will be able to use it.
Feature Comparison: Digital Comic & Archival Formats

Feature
BBF
CBZ (Zip)
CBR (Rar)
PDF
EPUB
Folder

Random Page Access
✅
✅[8]
✅[8]
✅
❌
✅

Native Data Deduplication
✅
❌
❌
⚠️ [1]
❌
❌

Per-Asset Integrity (XXH3)
✅
⚠️[9]
⚠️[9]
❌
❌
❌

4KB Sector Alignment
✅
❌
❌
❌
❌
❌

Native Sections/Chapters
✅
❌
❌
✅
✅
❌

Arbitrary Metadata (UTF-8)
✅
⚠️ [2]
❌
✅
✅
❌

Mixed-Codec Support
✅
✅
✅
❌
✅
✅

DirectStorage/mmap Ready
✅
❌
❌
❌
❌
⚠️ [3]

Low Parser Complexity
✅
⚠️ [4]
❌
❌
❌
✅

Bit-Rot Detection
✅
⚠️ [5]
⚠️ [5]
❌
❌
❌

Streaming-Friendly Index
⚠️ [6]
⚠️ [6]
❌
✅ [7]
⚠️
❌

Wide Software Support
❌
✅
✅
✅
✅
✅

[1] - PDF supports XObjects to reuse resources, but lacks native content-hash deduplication; identical images must be manually referenced.
[2] - CBZ does not support metadata natively in the ZIP spec; it relies on unofficial sidecar files like ComicInfo.xml.
[3] - While folders allow memory mapping, individual images within them are rarely sector-aligned for optimized DirectStorage throughput.
[4] - ZIP/RAR require large, complex libraries (zlib/libarchive); BBF is a "Plain Old Data" (POD) format requiring only a few lines of C++ to parse.
[5] - ZIP/RAR use CRC32, which is aging, collision-prone, and significantly slower to verify than XXH3 for large archival collections. See [8].
[6] - Because the index is at the end (Footer), web-based streaming requires a "Range Request" to the end of the file before reading pages.
[7] - PDF supports "Linearization" (Fast Web View), allowing the header and first pages to be read before the rest of the file is downloaded.
[8] - As Reddit properly corrected me, ZIP/RAR does have random access.
[9] - While I think CRC32 is a legacy hash format, ZIP/RAR does have verification ability, though somewhat outdated. See [5].
Graphical Comparison (BBF vs. CBZ)

Features
Content Deduplication
BBF uses XXH3_64 hashing to identify identical pages. If a book contains duplicate pages, the data is stored exactly once on disk while being referenced multiple times in the Page Table.
Archival Integrity
BBF stores a 64-bit hash for every individual asset. The bbfmux --verify command can pinpoint exactly which page has been damaged, rather than simply failing to open the entire archive.
Mixed-Codec Support
Preserve covers in Lossless PNG while encoding internal story pages in AVIF to save 70% space. BBF explicitly flags the codec for every asset, allowing readers to initialize the correct decoder instantly without "guessing" the file type.

CLI Usage: bbfmux
The included bbfmux tool is a reference implementation for creating and managing BBF files.
CLI Features
The bbfmux utility provides a powerful interface for managing Bound Book files:

Flexible Ingestion: Create books by passing individual files, entire directories, or a mix of both.
Logical Structuring: Add named Sections (Chapters, Volumes, Extras, Galleries) to define the internal hierarchy of the book.
Custom Metadata: Embed arbitrary Key:Value pairs into the global string pool for archival indexing.
Content-Aware Extraction: Extract the entire book or target specific sections by name.

Usage Examples
Create a new BBF
You can mix individual images and folders. bbfmux sorts inputs alphabetically, deduplicates identical assets, and aligns data to 4096-byte boundaries. See Advanced CLI Usage for how to specify your own custom page orders.
# Basic creation with metadata
bbfmux cover.png ./chapter1/ endcard.png \
--meta=Title:"Akira" \
--meta=Author:"Katsuhiro Otomo" \
--meta=Tags:"[Action, Sci-Fi, Cyberpunk]" \
akira.bbf
Hierarchical Sections (Volumes & Chapters)
BBF supports nesting sections. By defining a Parent relationship, you can group chapters into volumes. This allows readers to display a nested Table of Contents and enables bulk-extraction of entire volumes.
Syntax: --section="Name":Page[:ParentName]
# Create a book with nested chapters
bbfmux ./manga_folder/ \
--section="Volume 1":1 \
--section="Chapter 1":1:"Volume 1" \
--section="Chapter 2":20:"Volume 1" \
--section="Volume 2":180 \
--section="Chapter 3":180:"Volume 2" \
manga.bbf
Verify Integrity
Scan the archive for bit-rot or data corruption. BBF uses XXH3_64 hashes to verify every individual image payload.
bbfmux input.bbf --verify
Extract Data
Extract the entire book, a specific volume, or a single chapter. When extracting a parent section (like a Volume), bbfmux automatically includes all child chapters.
Extract a specific section:
bbfmux input.bbf --extract --section="Volume 1" --outdir="./Volume1"
Extract the entire book:
bbfmux input.bbf --extract --outdir="./unpacked_book"
View Metadata & Structure
View the version, page count, deduplication stats, hierarchical sections, and all embedded metadata.
bbfmux input_book.bbf --info

Advanced CLI Features
bbfmux also supports more advanced options, allowing full-control over your .bbf files.
Custom Page Ordering (--order)
You can precisely control the reading order using a text file or inline arguments.

Positive Integers: Fixed 1-based index (e.g., cover.png:1).
Negative Integers: Fixed position from the end (e.g., credits.png:-1 is always the last page).
Unspecified: Sorted alphabetically between the fixed pages.

# Using an order file
bbfmux ./images/ --order=pages.txt out.bbf

# pages.txt example:
cover.png:1
page1.png:2
page2.png:3
credits.png:-1
Batch Section Import (--sections)
Sections define Chapters or Volumes. You can target a page by its index or filename.
# Target by filename
bbfmux ./folder/ --section="Chapter 1":"001.png" out.bbf

# Using a sections file
bbfmux ./folder/ --sections=sectionexample.txt out.bbf

# sectionexample.txt example (Name:Target[:Parent]):
"Volume 1":"001.png"
"Chapter 1":"001.png":"Volume 1"
"Chapter 2":"050.png":"Volume 1"
Targeted Verification
BBF allows for verification of data to detect bit-rot.
# Verify everything (All assets and Directory structure)
bbfmux input.bbf --verify

# Verify only the directory hash (Instant)
bbfmux input.bbf --verify -1

# Verify a specific asset by index
bbfmux input.bbf --verify 42
Range-Key Extraction
The --rangekey option allows you to extract a range of sections. The extractor starts at the specified --section and stops when it finds a section whose title matches the rangekey.
# Extract Chapter 2 up until it hits Chapter 4
bbfmux manga.bbf --extract --section="Chapter 2" --rangekey="Chapter 4" --outdir="./Ch2_to_Ch4"

# Extract Volume 2 until it encounters the string "Chapter 60"
bbfmux manga.bbf --extract --section="Volume 2" --rangekey="Chapter 60" --outdir="./Volume_2_to_Chapter_60"

License
Distributed under the MIT License. See LICENSE for more information.

About

Bound Book Format: A high-performance, DirectStorage-native container format for comics and manga

Topics

multimedia

storage

container

manga

comics

file-format

mmap

cbz

archival

tachiyomi

cbx

file-format-library

directstorage

mihon

multimedia-tools

libbbf

cbz-alternative

cbx-alternative

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity
Stars

193
stars
Watchers

1
watching
Forks

2
forks

Report repository

Releases
2

v1.1.0 - Concomita [Stable]

Latest

Jan 2, 2026

+ 1 release

Packages
0

No packages published

Contributors
2

ef1500

ThatOneCalculator
Kainoa Kanter

Languages

C++
98.6%

C
1.3%

CMake
0.1%

Footer

© 2026 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Community

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

Bound Book Format (BBF) represents a significant advancement in digital comic and manga storage, specifically designed to leverage modern hardware capabilities and address limitations of existing formats. Developed by ef1500, BBF is a high-performance, DirectStorage-native container format that offers enhanced efficiency, integrity checks, and mixed-codec support. This summary will delve into the key features and technical details of BBF, highlighting its intended target audience – college graduates with a technical background.

The core design philosophy of BBF centers around direct access to memory using Memory Mapping (mmap/MapViewOfFile) within the bbfmux reference implementation. Instead of relying on intermediate buffers, files are mapped directly into the process address space, achieving performance speeds closer to the limits of NVMe drives. This approach contrasts with traditional formats like CBZ and CBR, which often introduce performance bottlenecks due to multiple file reads and writes. The document emphasizes BBF’s suitability for DirectStorage, a feature focused on seamless, low-latency data access, directly benefiting from this optimized mapping technique.

A key technical innovation is the format’s Footer-indexed binary layout. This structure allows for rapid append-only creation of files and immediate random access to any page without scanning the entire archive. This contrasts with formats requiring full scans for retrieval. The file structure includes a Header (13 bytes), containing critical information like the BBF magic number, versioning data, and initial padding. Following that is the Page Data, padded to 4096-byte boundaries – a deliberate choice critical for alignment with DirectStorage. Subsequent sections include a String Pool (deduplicated null-terminated strings for metadata), an Asset Table (using XXH3 hashes for parallel integrity checks), a Page Table (mapping logical pages to assets), a Section Table (defining hierarchical chapters/volumes), and a Metadata Table (supporting flexible archival indexing).

The integrity validation process utilizes Parallel XXH3_64 hashing. This is done across multiple cores during verification, dramatically speeding up the process compared to traditional CRC32 checks. The Parallel XXH3_64 hashing allows the verifier to pinpoint the exact page affected by corruption, offering significantly improved recovery capabilities. The bbfmux reference implementation uses XXH3_64 hashes, reflecting a commitment to robust data validation.

BBF's mixed-codec support is another crucial feature, enabling the preservation of cover images in losslessly high-quality PNG while encoding internal story pages in the more space-efficient AVIF format. The explicit codec flags within the Asset Table allow readers to initialize the appropriate decoder, removing the need for guesswork and promoting flexibility.

The documentation details the CLI usage of the bbfmux utility, a reference implementation for creating and managing BBF files. The utility incorporates several advanced features: Custom Page Ordering (using fixed or negative indexes), Section import, Targeted verification that can be done by section name or even a range of pages. These refined mechanisms give users granular control over their BBF files.

The document clearly defines the key differences between BBF and established formats like CBZ, CBR, and PDF, highlighting BBF’s strengths in areas such as random page access, deduplication, native integrity checks, and direct storage compatibility. The comparison emphasizes BBF’s superior performance and efficiency for modern storage technologies.

The technical design leverages C++17 compliant compilers (GCC/Clang/MSVC), and it recommends the use of the XXHash library for its speed and efficiency. The document stresses the significance of 4KB sector alignment, crucial for DirectStorage, and details the inclusion of padding within the file structure.

Finally, the “Usage Examples” section provides practical demonstrations of how to create, manage, and verify BBF files using the bbfmux utility, demonstrating the advanced CLI features such as Custom Page Ordering and Section import. This provides a solid understanding for college graduates with a strong technical background.

In essence, BBF represents an innovative approach to digital comic and manga storage, optimized for the demands of modern hardware and providing a superior user experience than traditional formats.