Library

Libraries are self-contained directories that store all your data, metadata, and thumbnails in one place. Each library lives in a single folder with a .sdlibrary extension. You can move libraries between machines, back them up to external drives, or share them with others by copying the directory. When you open a library, Spacedrive loads its database and configuration into memory and locks it to prevent corruption from concurrent access.

Structure

Each library contains library.json for configuration and metadata, database.db for the SQLite database, and a thumbnails/ directory with two-level sharding for performance. The thumbnails directory includes metadata.json for generation settings. A .sdlibrary.lock file appears when the library is open to prevent multiple processes from accessing it simultaneously.

Future directories include previews/ for full-size previews, indexes/ for search indexes, and exports/ for temporary exports.

Core Components

The LibraryManager creates, opens, and discovers libraries on your system. Each active Library instance holds a database connection and loaded configuration. The LibraryConfig stores settings like thumbnail quality and sync preferences in library.json.

Working with Libraries

Create a library with create_library("My Photos", None). Omit the path to use your default libraries directory. Open an existing library with open_library() by providing its path. The manager checks for lock files and loads configuration before returning the instance.

Scan your system for libraries with scan_for_libraries(). This searches common locations and returns metadata without opening each library.

Thumbnail Management

Libraries store thumbnails using content-addressed storage with two-level directory sharding. Save thumbnails with save_thumbnail(), check existence with has_thumbnail(), and retrieve them with get_thumbnail(). Thumbnails organize automatically into subdirectories based on their content hash.

Configuration

The library.json file stores all library settings:

<ResponseField name="id" type="string">
  Unique UUID for the library
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the library
</ResponseField>

<ResponseField name="settings" type="object">
  User-configurable options including thumbnail quality and sync preferences
</ResponseField>

<ResponseField name="statistics" type="object">
  Cached counts and sizes for quick display
</ResponseField>

Portability

Self-contained libraries work immediately after copying to a new location with zero configuration. Copy the entire folder to create a complete backup. Store libraries on external drives, network shares, or cloud-synced folders for automatic backup.