BitScribe

Documentation & Support Hub

Everything you need to audit, catalog, and optimize your local media collection with precision.

Guide Estimated time: 5 minutes

Quick Start Guide

Welcome to BitScribe Steward! Follow these simple steps to start auditing, analyzing, and cataloging your digital media collection.

Add Folders to Scan

Launch BitScribe Steward on your computer.
At the top of the left sidebar, locate the Media Scanner section.
Click + Add Folder to browse and select directories containing your movies, TV shows, or audio tracks.
You can queue multiple top-level folders simultaneously across different local drives.

Run the Scan

With your folders queued, click the Start Scan button.
BitScribe safely traverses your files, inspecting containers, video codecs, bitrates, audio tracks, and subtitle availability without altering files.
Track progress in real time as the engine probes your library for potential corruption or stream incompatibilities.

View Your Scan Results

📊 Analyze Dashboard

View interactive visual charts, health metrics, and instant alerts for duplicate titles or corrupted media files. Use the metric filters to hone in on specific alerts.

📚 Library Dashboard

Browse a searchable, sortable list of every media item. Filter by category or top-level folder, sort by headers, and customize column layouts.

Export Custom Reports

Export your catalog in your preferred format directly from the Export Formats block in the left pane:

📊 Excel (.xlsx)
🌐 HTML Report
📑 CSV Spreadsheet
💻 JSON Payload

Customize Compatibility Rules (Optional)

Optimizing for Plex, Jellyfin, or Emby? Visit the Options dashboard to customize Direct Play hardware thresholds (bitrates, codecs, max resolutions). BitScribe automatically recalculates your compatibility scores in real time!

Manual Complete Feature Breakdown

User Manual

BitScribe Steward is a comprehensive digital media library suite built to audit, catalog, and diagnose local media collections.

1. Introduction

BitScribe Steward provides deep technical insights into file formats, codecs, streaming viability, and overall library health through an intuitive user interface. Operating in a strictly read-only mode, BitScribe ensures your media files remain completely unaltered.

2. Dashboards Overview

2.1 Media Scan & Report Export

The primary hub for queueing directory paths, running high-speed scans, and generating formatted audit reports. Supports batch folder queueing and real-time scanning feedback.

2.2 Analyze Dashboard

Provides visual distribution charts (Codecs, Resolutions, Categories) alongside instant health alerts for corrupted files, bitrate anomalies, and duplicate titles. Includes a top-level folder clutter toggle to focus on specific drives.

2.3 Library Dashboard

A high-density grid showing container types, video/audio codecs, bitrates, duration, file sizes, and subtitle tracks. Powered by deferred searching for smooth 60fps rendering across large collections.

2.4 Options Dashboard

Configure Direct Play compatibility rules for home media servers (Plex, Jellyfin, Emby). Custom limits instantly re-evaluate media health without requiring a rescan.

2.5 Help Dashboard

In-app glossary explaining media terminology (e.g. Transcoding, Container vs Codec, Bitrate) and step-by-step feature guides.

3. Core Capabilities

📡 Streaming Compatibility Check

Evaluates files against hardware profiles to detect direct play blockers, preventing server CPU strain and buffering during streaming.

🔍 The Duplicate Hunter

Compares structural video metadata and audio track details to locate redundant copies (e.g. 4K vs 1080p duplicates or duplicate audio files).

⚠️ Health & Anomaly Scan

Identifies corrupted files failing header probes and flags abnormal bitrates (e.g. uncompressed audio/video or extreme compression).

💬 Subtitle Detective

Checks video files for embedded subtitle streams as well as external `.srt` subtitle files in the same directory.

FAQ Wiki Frequently Asked Questions

FAQ & Knowledge Base

Find quick answers to common questions regarding BitScribe Steward features, safety, compatibility, folder structures, codecs, and reports.

General & Safety

What is BitScribe Steward? ▼

BitScribe Digital Media Library Steward (DMLS) is a powerful discovery tool that seamlessly catalogs your movies, TV shows, music, and documentaries.

Once scanned, it provides actionable insights to refine your library—helping you identify missing assets like subtitles, pinpoint low-quality or bloated files, and uncover hidden duplicates you didn't even know you had.

Does BitScribe modify or delete my files? ▼

No! BitScribe operates strictly in a read-only capacity. It scans your files and reads their metadata without ever altering, renaming, or deleting the actual media files on your drives.

What operating systems are supported? ▼

BitScribe Steward natively supports Windows and macOS (with Apple Silicon native arm64 optimization).

Library Folder Structure & Scanning

Can I organize my movies into alphabetical or nested subfolders? ▼

Yes, absolutely! BitScribe scans all directory levels in your file path. As long as some parent folder contains a matching category keyword (like Movies, Films, etc., even if it is nested like movies/a/MovieTitle/MovieName.mkv), it is automatically identified as a movie. Nested folder hierarchies of any depth are fully supported!

What folder names does BitScribe recognize natively, and what happens otherwise? ▼

BitScribe matches folder names using flexible keyword checks (case-insensitive):

Movies: Movies, Movie, Films, Film, Cinema, Cinemas, UHD, Foreign
TV Shows: TV Shows, TV Show, TV, Series, Shows, Cartoons, Anime
DocuSeries: DocuSeries, Documentary Series, Documentary Show
Documentaries: Documentaries, Documentary, Docs, Doc
Shorts: Shorts, Short films, Short film, Shortfilms
Concerts: Concerts, Concert, Live Shows, Live Show, Live Performances, Live Performance
Music: Music, Audio, Soundtracks, Compilations

If a folder path doesn't contain any recognizable keyword, files default to Other, unless the filename has explicit TV formats (like S01E01) or Years (like (1999)), which enables smart auto-classification fallback.

What happens if an "Extras" folder is inside a "Season" folder? ▼

The scanner parses this flawlessly! When a folder path matches "Extras" (or specials, bonus features, deleted scenes, behind-the-scenes, etc.), BitScribe recursively climbs the folder tree to skip any season folders (e.g. Season 01), correctly identifying the parent TV Show or DocuSeries title as the main group name.

I have a top-level library folder called "Specials". How will BitScribe handle this? ▼

BitScribe handles this beautifully! Many media managers use a dedicated top-level folder called Specials for seasonal gems or holiday one-offs.

- Smart Detection: When Specials is scanned as a top-level parent folder, BitScribe bypasses the generic "Extras" tag and intelligently groups these one-offs under the Movies category (if they have a release year or default to standalones) or under TV Shows (if filename contains episode templates like S00E01).
- Nesting Extras: Behind-the-scenes "Extras" subfolders placed inside individual show or movie folders (e.g., TV Shows/Breaking Bad/Specials/) are still correctly identified as native companion Extras!

Features & Capabilities

How does the Duplicate Hunter work? ▼

The Duplicate Hunter looks past filename differences to compare structural metadata (duration, container, track counts, codecs). For music, it cross-references title, artist, and track lengths to highlight duplicate files.

How does Video vs Music Duplication reporting differ? ▼

Video Duplication strips release keywords/years and matches films within a 3-minute playtime limit.

Music Duplication parses ID3 Metadata (Title + Artist) and checks file lengths within a tighter 30-second window, flagging duplicates and favoring FLAC and 320Kbps MP3 files for music. MP3s with bitrates lower than 320Kbps will be flagged.

What makes a video file "Streaming Unfriendly"? ▼

Files are flagged as unfriendly if they use mismatched codecs, old codecs that aren't designed for streaming (like DivX or Xvid), unoptimized containers (like AVI), or potentially the newest "bleeding edge" codecs that are not yet well supported in consumer hardware. These issues force your media server to transcode the video on the fly, which can cause playback buffering and high server CPU usage.

What is the Streaming Compatibility Check? ▼

Incompatible media formats force servers like Plex, Jellyfin, or Emby to convert ("transcode") video on the fly, consuming heavy CPU usage. BitScribe evaluates HEVC, H.264, bitrates, and audio formats against your target hardware to verify Direct Play viability.

Can it detect corrupted files? ▼

Yes. Files with broken container headers or invalid stream probes are flagged as corrupted anomalies, allowing you to clean up unplayable files.

What does the "Discovery Skip / Unresolved" count refer to? ▼

In Discovery Mode, items using rare, unknown codecs, or files utilizing codecs unchecked in your current Settings column lists are skipped rather than indexed so the library steward can review them for catalog safety.

Usage & Export Options

Can I customize individual transcode alert thresholds? ▼

Yes. All video codecs lists, surround patterns, and stereo audio profiles can be edited inside the Library Stewardship Options menu under the Options page tab. The evaluator updates diagnostic outputs instantly.

What export options are available? ▼

Supported export formats include formatted Excel Workbooks (.xlsx), interactive single-file HTML Web Reports with embedded charts, CSV spreadsheets, and raw JSON payloads.

v1.5.0 Spec Architecture & Database Schema

Technical Reference

Low-level architectural overview, SQLite schema specs, IPC communication flows, and performance optimizations.

1. Architecture Overview

BitScribe Steward follows a monorepo architecture bridging a high-performance Rust backend with a modern React frontend:

Frontend: React 19, Vite, Tailwind CSS. Handles state management, UI filtering, and data visualizations.
Backend: Tauri (Rust). Handles native OS interactions, zero-allocation filesystem traversal, and sidecar binary execution.
Database: Local SQLite database with memory-mapped I/O and WAL journaling for high-speed bulk ingestion.

2. Package Structure

apps/steward

Primary entry point with React UI and Tauri Rust app.

packages/core-db

Database interactions & primary scanning loop orchestrator.

packages/core-eval

Stream compatibility heuristics & deduplication algorithms.

packages/core-export

Data serialization for Excel, CSV, JSON, and HTML reports.

3. Database Schema

Core store schema for scanned media files (`scanned_files` table):

CREATE TABLE scanned_files (
  id TEXT PRIMARY KEY,
  filename TEXT, filePath TEXT, category TEXT, container TEXT,
  sizeGB REAL, durationMins REAL, year INTEGER,
  videoCodec TEXT, videoResolution TEXT, videoBitrateMbps REAL, videoBitDepth TEXT, videoFrameRate REAL,
  audioTracks TEXT, subtitleTracks TEXT, tags TEXT, audioBitrate REAL, audioSampleRate INTEGER,
  isCorrupted INTEGER, errorMessage TEXT, hasEmbeddedPoster INTEGER, bitrateAnomaly INTEGER, bitrateAnomalyReason TEXT, topLevelFolder TEXT,
  streamFriendlyLevel TEXT, streamFriendlyReason TEXT, streamFriendlySuggestion TEXT, streamFriendlyEvaluated INTEGER,
  chapterCount INTEGER, rawAudioCodec TEXT, physicalAudioChannels INTEGER,
  matchedOnlineId TEXT, fileUuid TEXT, hasExternalSubtitles INTEGER, embeddedSubtitleLanguages TEXT,
  author TEXT, narrator TEXT, publisher TEXT, bookSeries TEXT, seriesIndex REAL, isbn TEXT, pageCount INTEGER
);

CREATE INDEX idx_scanned_files_filePath ON scanned_files(filePath);

⚡ SQLite Optimization PRAGMAs:
PRAGMA mmap_size = 268435456; PRAGMA threads = 4; PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL;

4. Execution Flows & Platform Logic

4.1 Zero-Allocation Traversal & ffprobe Probing

Directory walking is offloaded to a Tauri IPC Rust command (`walk_dir`). Case-insensitive exclusions skip hidden files (e.g. macOS `._` AppleDouble or `__MACOSX`) without heap allocations. Valid media files are passed to a bundled `ffprobe` sidecar binary to extract metadata.

4.2 Global Memoization & Smooth Searching

Deduplication mapping and compatibility evaluations are memoized in global caches (`_globalEvalCache`), decoupling computation from React renders. UI filtering uses React 18's useDeferredValue to maintain 60fps responsiveness across datasets of 30,000+ records.

4.3 macOS Gatekeeper Bypass

To prevent Apple Gatekeeper blocking on macOS, the backend extracts a zipped native Apple Silicon (`arm64`) `ffprobe` binary into the user's ~/Library/Application Support/ directory at runtime.