Sora2 Vault Viewer

A lightweight local viewer for browsing Sora manifest exports together with local mp4 and txt files.

This project assumes the data structure produced by SoraVault 2.0, including soravault_manifest_*.json files such as soravault_manifest_merged_*.json and the sora_v2_* export directory layout. This repository does not include or reuse SoraVault source code. It only works with the data structure generated by SoraVault 2.0 exports.

Overview

• Merges all soravault_manifest_*.json files found in sora2_data/
• Matches manifest items with local files from SoraVault 2.0 export directories
• Plays local videos inline in a dark gallery UI with a right-side details panel
• Searches by prompt, genId, postId, taskId, TXT content, and date range with auto-apply filtering
• Supports pagination, page size selection, source filtering, and sorting by date, prompt, duration, views, likes, and source order
• Supports keyboard browsing across gallery cards with Tab, Enter, Space, and arrow keys
• Shows manifest-derived metadata such as posted by, likes, views, loaded manifest names, and TXT content

For release notes and change summaries, see CHANGELOG.md.

UI Counts

The summary strip at the top of the viewer uses these meanings:

• Library: total indexed items across both manifest-backed entries and local-only entries
• Playback: items that have a local mp4 file and can play inside the viewer
• Text: items that have a local txt sidecar file
• Manifest Gap: local-only items found on disk that could not be matched back to manifest metadata
• Sources: the number of unique indexed source buckets such as profile, liked, drafts, user sources, and char sources
• xx-yy of nnnn items: the current page range inside the filtered result set

Quick Start

Requirements:

• Node.js 22.13+
• Verified in practice with Node.js 24

Windows (PowerShell):

git clone https://github.com/tinatsu-nomy/sora2-vault-viewer.git
cd sora2-vault-viewer
mkdir sora2_data

Project structure:

app/
  public/
    index.html
    app.js
    styles.css
  server.js
sora2_data/
  soravault_manifest_*.json
  sora_v2_*/

Download your Sora2 export data into sora2_data/ so the layout looks like this:

sora2_data/
  soravault_manifest_*.json
  sora_v2_*/

Then start the viewer:

npm start

The app starts at http://localhost:3210 by default and automatically moves to the next free port if needed. To stop the server, return to the terminal where it is running and press Ctrl+C.

Electron desktop app:

npm install
npm run start:electron

Portable Windows build:

npm install
npm run build:electron

The Electron app embeds the existing local HTTP viewer and opens it in a desktop window.

Portable build notes:

• Place sora2_data/ in the same parent folder as the generated executable, or set SORA_DATA_DIR explicitly before launch
• Recommended portable layout:

AnyFolder/
  Sora2_Vault_Viewer-portable.exe
  sora2_data/
    soravault_manifest_*.json
    sora_v2_*/

• For electron-builder portable builds, the app prefers PORTABLE_EXECUTABLE_DIR\sora2_data\
• Electron stores settings in app.getPath("userData")\app-data\viewer-config.json
• If SORA_DATA_DIR is not set, Electron first uses the dataDir value from that settings file
• If no saved dataDir exists yet, Electron falls back to Sora2_Vault_Viewer-portable.exe's sibling sora2_data\
• If you move only the EXE to a different folder after first launch, the app may continue using the previously saved dataDir
• If the app does not read the sora2_data\ next to the EXE that you expect, set SORA_DATA_DIR explicitly or update viewer-config.json
• If you change the data directory after the app has already been launched, initialize app-data\ as well so the saved dataDir and caches do not keep pointing at the previous location
• Startup now prefers the last completed SQLite cache so the viewer opens faster on large libraries
• After adding or changing manifests, videos, or TXT files while the app is closed, click Rescan to rebuild the cache from disk

Distribution:

• Release page: v0.2.6.3 release
• Portable download: Sora2_Vault_Viewer-portable.exe
• Place sora2_data/ in the same folder as Sora2_Vault_Viewer-portable.exe before launch
• The app stores settings, SQLite cache, and TXT cache under app.getPath("userData")\app-data\
• On Windows, this is typically C:\Users\<your-user-name>\AppData\Roaming\Sora2 Vault Viewer\app-data\
• The Electron settings file is app.getPath("userData")\app-data\viewer-config.json
• On Windows, this is typically C:\Users\<your-user-name>\AppData\Roaming\Sora2 Vault Viewer\app-data\viewer-config.json
• If viewer-config.json contains dataDir, Electron uses that path before checking the EXE's sibling sora2_data\ when SORA_DATA_DIR is not set
• PORT is not stored in viewer-config.json; the default HTTP port is 3210 and can be overridden with the PORT environment variable
• Example viewer-config.json:

{
  "dataDir": "D:\\SoraExports\\sora2_data"
}

• Example settings screen for configuring the data directory:

• Windows may show SmartScreen or other security prompts for unsigned executables

Uninstalling the portable Windows app:

• The portable build does not install itself into Program Files and does not add a standard Windows uninstaller
• To remove the app itself, close it and delete Sora2_Vault_Viewer-portable.exe
• To remove your exported data from the same portable folder, also delete the adjacent sora2_data/ folder if you no longer need it
• To remove saved settings and caches, delete app.getPath("userData")\app-data\
• On Windows, this is typically C:\Users\<your-user-name>\AppData\Roaming\Sora2 Vault Viewer\app-data\
• Deleting app-data\ removes viewer-config.json, the SQLite cache, and the TXT cache
• If you want to keep your export data but reset the app state, delete only app-data\ and keep sora2_data/

Optional environment variables:

• PORT: starting port for the local server. Defaults to 3210
• SORA_BIND_HOST: bind host for the HTTP server. Defaults to 127.0.0.1
• SORA_DATA_DIR: override the data directory location
• SORA_VIEWER_ROOT: override the repository root when sora2_data/ lives directly under a different parent directory
• SORA_APP_DATA_DIR: override the directory used for SQLite, TXT cache, and the Electron settings file
• SORA_ENABLE_SQLITE_CACHE: defaults to enabled. Set 0 to disable the local SQLite cache
• SORA_SQLITE_PATH: override the SQLite database file path
• SORA_SQLITE_RENEW_ON_START: set 1 to delete the cached SQLite database before startup and force a full rebuild from manifests and local files

Common examples:

# default
npm start

# disable the SQLite cache
$ENV:SORA_ENABLE_SQLITE_CACHE = "0"
npm start

# custom data directory
$ENV:SORA_DATA_DIR = "D:\SoraExports\sora2_data"
npm start

# force a fresh SQLite rebuild on startup
$ENV:SORA_SQLITE_RENEW_ON_START = "1"
npm start

# custom port
$ENV:PORT = "3211"
$ENV:SORA_DATA_DIR = "D:\SoraExports\sora2_data"
npm start

Data Layout

Add new manifest JSON files:

1. Copy the new soravault_manifest_*.json file into sora2_data/
2. Keep the soravault_manifest_*.json naming pattern so the viewer can detect it automatically Examples include soravault_manifest_2026-04-17.json and soravault_manifest_merged_*.json
3. Click Rescan
4. Confirm the file name appears in Loaded manifests

Add new local media and TXT files:

1. Put exported files into the matching source directory:
   • Example: sora_v2_profile
   • Example: sora_v2_liked
   • Example: sora_v2_drafts
   • Other SoraVault 2.0 sora_v2_* source directories are also supported
2. Keep each mp4 and txt pair together using the exported file names from SoraVault 2.0
3. Click Rescan
4. Confirm the new items appear in the gallery and detail view

How local files are linked to manifest JSON:

• The files must be placed in the matching source directory for that export type
• The mp4 and txt files must share the same stem
• The viewer must be able to match the local files to a manifest item using one or more identifiers such as generationId, taskId, postId, extracted ID tokens, or the file stem

In practice, a SoraVault 2.0 filename template such as {date}_{genId} has been confirmed to work with this viewer.

If these conditions are not met, the files can still appear as local-only items, but they will not be linked to manifest JSON metadata.

Troubleshooting

• If new manifests or files do not appear, click Rescan and then check Loaded manifests
• On large libraries, startup may show cached results from the last completed scan until you click Rescan
• Use the Renew next start checkbox when you want the next app launch to behave like SORA_SQLITE_RENEW_ON_START=1 once and then return to normal cached startup behavior
• If a manifest is malformed, the viewer skips it and continues indexing the remaining files
• If the UI shows an index, detail, or rebuild error, fix the underlying file issue and try Rescan again
• Run npm run check for syntax validation and npm test for the smoke test fixture
• Local only is enabled by default, so the initial feed focuses on files that exist locally
• The server binds to loopback (127.0.0.1) by default, so it stays local-only unless you explicitly override SORA_BIND_HOST
• The /media endpoint serves only indexed local mp4 and txt files
• Sora 1 data is not supported
• Local media, manifests, caches, and backup logs are intentionally excluded by .gitignore
• This repository is provided as-is, without warranty or guarantee of compatibility, correctness, completeness, or fitness for a particular purpose
• Behavior is intended for SoraVault 2.0 export layouts and is not guaranteed for other export formats or future versions

License

MIT