Oblecto repository guide

Scope

• Backend Node/ESM server lives in src/.
• Default Vue 2 frontend lives in Oblecto-Web/ and builds to Oblecto-Web/dist/.
• Backend tests are in tests/; helper scripts in scripts/.

Quick commands (from repo root)

• npm run dev (backend dev server via tsx)
• npm run build (backend build to dist/)
• npm run start (run built backend)
• npm run oblecto / npm run oblecto:dev (CLI)
• npm run build:web (frontend build; runs npm install inside Oblecto-Web/)
• npm test / npm run test:mocha / npm run test:startup

Config and data

• Config is read from /etc/oblecto/config.json (see src/config.ts).
• Default sqlite DB is /etc/oblecto/database.sqlite (see src/submodules/database.js).
• External metadata uses TVDB/TMDB keys from config.

Conventions

• ESM modules (package.json has "type": "module").
• dist/ and Oblecto-Web/dist/ are build outputs; avoid editing.
• node_modules/ and Oblecto-Web/node_modules/ are vendor.

Oblecto

What is it?

Oblecto is a self-hosted media server for streaming the media you already own. It indexes Movies and TV Shows, enriches them with metadata and artwork, and serves them through a web interface or compatible clients.

Features

• Movie and TV library indexing with background updates.
• Metadata and artwork from TMDb, TVDB, and Fanart.tv (bring your own API keys).
• Built-in web UI (Oblecto-Web) served by the backend.
• Jellyfin/Emby API emulation for compatible clients (port 8096).
• Streaming sessions with direct play and recode/HLS support (via FFmpeg).
• Optional federation and seedbox import support.
• CLI tools for setup, database init, and user management.

What Oblecto can do

• Scan folders of Movies/TV, identify items, and keep your library organized.
• Fetch posters, fanart, episode banners, descriptions, and ratings.
• Serve your library to the web UI and compatible Jellyfin clients.
• Track playback progress and provide "Next Up" for TV series.
• Store assets and metadata in a local database (SQLite by default).

Setup

Oblecto can be installed using NPM or directly from Git. We recommend NPM unless you plan to develop.

Quick start (npm)

1. Install: npm install -g oblecto
2. Initialize config and assets: oblecto init
3. Edit /etc/oblecto/config.json and set:
   • movies.directories and tvshows.directories
   • API keys: themoviedb.key, tvdb.key, fanart.tv.key
   • Database settings (SQLite by default)
4. Initialize the database: oblecto init database
5. Start the server: oblecto start (or oblecto start-tui)
6. Open the web UI at http://localhost:8080/web (or the port set in server.port)

From source (development)

1. Install dependencies: npm install
2. Build the web UI: npm run build:web
3. Build or run the backend:
   • npm run build then npm run start, or
   • npm run dev for live development
4. Use the CLI if needed: npm run oblecto (or npm run oblecto:dev)

Configuration notes

• Config path order: OBLECTO_CONFIG_PATH -> ./res/config.json -> /etc/oblecto/config.json
• Default SQLite file: /etc/oblecto/database.sqlite
• Sample config template: res/config.json

Need help? Ask in the gitter chat or check the setup guide: https://github.com/robinp7720/Oblecto/wiki/Getting-Started

Powered by