Omnifile

Omnifile is a local-first document viewer and format-aware editor for Visual Studio Code. The project opens supported files in regular editor tabs and keeps document handling local to the machine, with format-appropriate navigation in a dedicated Activity Bar container.

Version 0.1.0 is the initial release: local PDF and structured-text support together with image, audio, and inspected WebM, Matroska/MKV, MP4, M4V, and MOV video previews.

Release status

• Version: 0.1.0
• Marketplace ID: Dheovani.omnifile
• Release scope: PDF, selected text/structured-text formats, images, audio, and video
• Image scope: PNG, JPEG/JFIF, GIF, WebP, BMP, AVIF, ICO, passive SVG, Netpbm PBM/PGM/PPM/PNM, QOI, TGA, DDS, TIFF/TIF, JPEG 2000 JP2/J2K, JPEG XL, HEIF, and HEIC
• Audio scope: PCM or IEEE floating-point WAV, MPEG Audio Layer III (MP3), Ogg Vorbis, and native FLAC
• Video scope: inspected WebM and Matroska/MKV with VP8, VP9, or AV1, plus MP4/M4V/MOV with AVC/H.264 and optional AAC; the EBML formats also have bounded WebCodecs video and packaged local Opus audio decoding
• Security model: local processing only, no external upload, packaged PDF.js, strict webview CSP
• Current maturity: public preview; version 0.1.0 is prepared for its initial GitHub release and Marketplace publication

Included functionality

• Local PDF preview through a custom editor and Activity Bar navigator
• Multi-page rendering with packaged PDF.js assets and local worker setup
• Page thumbnails, page navigation, zoom, fit-to-page, fit-to-width, actual size, and rotation
• Search, text selection, and encrypted-PDF password handling inside the preview webview
• Optional text previews for .txt, .log, .json, .jsonl, .ndjson, .csv, .tsv, .md, .markdown, .xml, .yaml, and .yml
• Editable Raw mode for text-backed files using VS Code's native text-document model
• Safe Preview mode for structured content such as JSON, CSV/TSV, Markdown, and logs
• Privacy-safe diagnostics and runtime reporting for troubleshooting
• Deterministic renderer selection and guarded navigation/session state
• Optional readonly image editor for .png, .jpg, .jpeg, .jfif, .gif, .webp, .bmp, .avif, .ico, .svg, .pbm, .pgm, .ppm, .pnm, .qoi, .tga, .dds, .tif, .tiff, .jp2, .j2k, .jxl, .heif, and .heic
• Native image zoom, actual size, fit-to-window, fit-to-width, panning, rotation, and transparency background controls
• Animated GIF/WebP detection, bounded frame counts, and play/pause snapshots
• Header-based format, dimensions, aspect-ratio, bit-depth, and transparency metadata before browser decoding
• Optional readonly WAV/MP3/Ogg Vorbis/FLAC editor with native accessible playback controls, inspected codec metadata, and bounded title/artist/album extraction across their native tag containers
• Optional readonly video editor with bounded WebM, restricted Matroska, and ISO Base Media inspection, native MP4/M4V/MOV playback, WebCodecs VP8/VP9/AV1 fallback, local Opus audio fallback, and graceful codec failure

Validation evidence

These captures come from the real Extension Development Host and use project-generated demonstration resources only. The PDF fixture is a generated three-page document with text, vectors, a table, and embedded images; the video fixture is a small solid-color H.264/AAC clip.

Installation

Download the VSIX from GitHub Releases. In VS Code, open Extensions, select ... > Install from VSIX..., and choose the downloaded file. Use Reopen Editor With... on a supported file or the Omnifile: Open Image Preview, Open Audio Preview, Open Video Preview, Open Text Preview, or Open PDF commands.

Development setup

Prerequisites:

• Node.js 24
• npm
• Visual Studio Code compatible with the engine range declared in package.json

Install dependencies:

npm ci

Common workflow:

npm run build
npm run check
npm test

npm run package builds the VSIX and enforces release budgets of 4 MiB compressed, 12 MiB installed, 220 entries, and 6 MiB per entry. The verifier also rejects source files, source maps, tests, coverage output, and local fixtures, and requires the packaged runtime licenses and third-party notice. Run npm run package:budget to recheck an existing versioned VSIX without rebuilding it.

To run the extension locally in VS Code:

1. Open this repository in VS Code.
2. Press F5 to launch the Extension Development Host.
3. Use the command palette or Explorer context menu to open a PDF, supported text file, supported image, audio file, or supported video file.
4. Select the Omnifile action as needed through the editor title or the custom editor menu.

Privacy and local processing

Omnifile is designed to stay local-first. It does not upload document contents, names, metadata, or extracted text to a remote service. The packaged PDF.js runtime remains as part of the extension; no runtime CDN is used for document preview.

Security

The project uses strict webview CSPs, nonce-based script execution, bounded message validation, and safe DOM text handling for document-derived content. A dedicated security policy is maintained in SECURITY.md.

Roadmap and limitations

PNG, JPEG/JFIF, GIF, WebP, BMP, AVIF, ICO, and passive SVG currently use Chromium's packaged native image path. Animated GIF and WebP files play natively; Pause captures a bounded display snapshot and Play returns to the native animation. ICO directory entries are validated and their variant count is shown, but selecting individual variants is still planned. AVIF availability follows the Chromium codec bundled with the running VS Code version.

PBM, PGM, PPM, PNM, QOI, and TGA use dependency-free extension-host decoders. Netpbm covers ASCII, packed one-bit, 8-bit, and 16-bit big-endian samples. QOI covers every standard pixel operation and RGB/RGBA streams. TGA covers uncompressed and RLE true-color or grayscale images, honors image origins, and supports eight-bit alpha channels. All are normalized into an RGBA buffer and drawn by the fixed Canvas UI. Custom raster inputs are limited to 16 MiB and 4 million pixels, and only the decoded buffer crosses into the webview; their source directory is not exposed through localResourceRoots.

DDS preview uses the same bounded RGBA path for ordinary 2D textures. It supports masked 16-, 24-, and 32-bit RGB/RGBA pixels plus BC1/DXT1, BC2/DXT3, and BC3/DXT5 block compression. The base image level is displayed; mipmaps are not duplicated into memory. Cubemaps, volume textures, texture arrays, DX10 headers, and unsupported compression FourCCs are rejected explicitly rather than displaying an arbitrary surface.

TIFF/TIF preview uses the packaged, MIT-licensed tiff decoder and supports single-page and multi-page RGB, grayscale, and palette images within the custom-raster safety limits. Opening a TIFF parses its page directory and decodes only the first page. Other pages are decoded when selected, and navigator thumbnails are generated sequentially only after Thumbnail mode is enabled. TIFF navigation uses generic DocumentSection entries, so the Activity Bar and preview remain synchronized without TIFF-specific navigator code. The initial decoder supports uncompressed, LZW, Deflate, and PackBits data; unsupported orientations, floating-point samples, uncommon photometric models, and other compression schemes produce a clear error rather than an inaccurate preview.

JP2 containers and raw J2K codestreams reuse the packaged PDF.js OpenJPEG WASM decoder instead of adding another codec dependency. Omnifile validates JP2 boxes and the JPEG 2000 size/component marker before starting WASM, limits inputs to 16 MiB and four million pixels, normalizes grayscale or three-component decoded pixels into RGBA, and displays an enumerated JP2 color space when available. Extended-length JP2 boxes, ambiguous alpha/CMYK channel layouts, sample depths above 16 bits, and unsupported OpenJPEG features fail explicitly. Resolution-reduced decoding was evaluated but is not enabled yet because the current image metadata and layout contract must continue to report faithful intrinsic dimensions.

JPEG XL previews use a packaged single-threaded libjxl-derived WASM decoder from @jsquash/jxl. A format-owned bitstream parser validates raw codestream or jxlc container signatures and rejects dimensions above four million pixels before the codec can allocate the output raster. Decoder calls are serialized because the packaged Emscripten runtime owns mutable shared memory. The initial implementation renders one normalized 8-bit RGBA image; animation, partial jxlp codestream boxes, HDR/wide-gamut preservation, and advanced metadata are not supported yet.

HEIF and HEIC previews accept HEVC-branded still-image containers and use a vendored CSP-compatible libheif 1.23.3 build with libde265 1.0.16. Omnifile validates the ISO Base Media File Format box graph, codec brands, declared ispe dimensions, the 16 MiB input ceiling, and the four-million-pixel output ceiling before decoding. Each operation runs in a disposable worker with no Node filesystem/process surface, a 30-second deadline, cancellation, and bounded V8 old-generation/stack resources. The returned dimensions and RGBA length must match the validated container. The current slice displays the first top-level image as normalized 8-bit sRGB output; sequences, auxiliary-image selection, HDR/wide-gamut preservation, non-HEVC HEIF codecs, and editing are not supported. The patched runtime replaces the older npm wrapper; source checksums, licenses, and rebuild instructions are retained. Builds verify its SHA-256 and workers validate its version. No Docker or native decoder installation is required to use the extension.

SVG remains vector-based, but receives a stricter policy because it is active document content rather than a bitmap. Omnifile validates the complete UTF-8 document up to 4 MiB, allows local #fragment references, and rejects scripts, event attributes, foreignObject, SMIL animation, DTD/entities, processing instructions, embedded images, external styles, and non-local resource references. The raw SVG markup is never inserted into the webview DOM; accepted files are decoded only through Chromium's restricted image context. SVG files needing rejected active or embedded features currently show an error instead of being partially rewritten.

Frame stepping and playback speed are intentionally outside M4; 3D models, Office, and OpenDocument formats remain planned. Native raster images are readonly and limited to 128 MiB, 32,768 pixels per dimension, and 100 million pixels. Custom rasters, including TIFF and HEIF/HEIC, are limited to 16 MiB and 4 million decoded pixels per page because decoding allocates a normalized RGBA copy; TIFF documents are additionally limited to 1,000 pages.

The audio editor accepts local PCM/float WAV, MP3 Layer III, Ogg Vorbis, and native FLAC files after bounded header inspection. Ogg inspection validates page CRCs, stream sequencing, packet segmentation, and codec identification metadata instead of trusting .ogg or .oga extensions. Title, artist, and album can be read from WAV LIST/INFO, ID3v2, Ogg Vorbis comments, and FLAC Vorbis comments when they are already present in the initial one MiB buffer. Values are normalized, length-limited, and inserted with DOM text APIs; artwork and chapters are intentionally not decoded. The player streams the selected file through a webview resource URI into Chromium's native <audio> element, so the extension host does not duplicate the complete media buffer. Browser codec availability still follows the Chromium build bundled with VS Code. Valid Ogg Opus and ADTS/AAC reference streams failed playback validation in the current VS Code 1.134 runtime baseline, so .opus and .aac are deliberately not contributed yet. Audio-only MP4/M4A, metadata artwork display, playlists, chapters, waveform generation, editing, and transcoding are also not supported.

The video editor recognizes local .webm, .mkv, .mp4, .m4v, and .mov files only after container-specific bounded inspection. WebM and Matroska require their exact EBML document type, a VP8, VP9, or AV1 video track, supported optional Vorbis/Opus audio, dimensions, and sane resource limits. AV1 fallback additionally requires a valid bounded av1C codec configuration record; its profile, level, tier, and bit depth become the exact WebCodecs codec string instead of being guessed from the extension. Matroska is deliberately narrower than the general container: Attachments and codecs outside this WebM-compatible subset are rejected, and MKV always uses the inspected range-based WebCodecs path instead of assuming Chromium can play video/x-matroska. MP4/M4V/MOV inspection walks only top-level box headers, skips media payloads, limits moov metadata to 4 MiB, and accepts one AVC/H.264 video track with optional AAC Main, LC, SSR, or LTP audio. MP4/M4V require an MPEG-4-compatible ftyp; MOV separately requires the QuickTime qt brand and supports the bounded version 0 and version 1 audio sample layouts, including QuickTime's nested wave descriptor. The exact codec declaration from avcC and esds must pass Chromium's MP4 codec-capability check before the local media URI is loaded; successful loadedmetadata remains the definitive container/runtime validation. Renaming between the supported containers does not bypass inspection. HEVC, AV1 in ISO Base Media, multiple audio tracks, Matroska Attachments, and the broader MKV codec family are not supported.

When WebM chapters are present in the initial metadata window, the Activity Bar uses their normalized titles and timestamps; otherwise every accepted video container exposes adaptive time markers every 30 seconds for short videos, two minutes for medium videos, five minutes for videos up to two hours, and ten minutes for longer media. Unusually long timelines increase the interval to remain below 240 sections. Selecting a section seeks the player, while playback and manual seeking update the active section. Timeline thumbnails are disabled in list mode and generated only for visible navigator items after thumbnail mode is selected. Native MP4/M4V/MOV playback uses a separate muted media element so thumbnail seeking never moves the main player.

Local sidecar subtitles are supported for both playback backends. Place a UTF-8 WebVTT or SubRip file beside the video with the same base name, such as lecture.mp4 plus lecture.vtt or lecture.srt; WebVTT takes precedence when both exist. Subtitle discovery and parsing happen in the extension host, remain local, and are limited to a 1 MiB file, 5,000 cues, and 4,000 characters per cue. Basic cue markup is reduced to plain text, styling and positioning are intentionally ignored, and the webview displays the result only through textContent. The common full-screen target retains sidecar subtitles for both playback backends. Embedded subtitle tracks, subtitle selection, and encoding detection beyond UTF-8 are not supported yet.

Chromium remains the first playback backend for WebM and ISO Base Media, but native media and the WebCodecs canvas use one extension-owned VS Code-themed control bar. It provides play/pause, seeking, mute, continuous volume, and full-screen controls. When the player has focus, Space, Left/Right Arrow, M, and F provide equivalent keyboard access.

The VS Code runtime advertises VP8/VP9 through canPlayType but rejects the deterministic fixtures during native decoding, while VS Code 1.136 does not advertise the generated AV1 WebM. Omnifile therefore builds a range-based index of at most 10,000 known-size EBML clusters and loads only the requested cluster for WebCodecs playback; Matroska always takes this inspected path. During playback, one next encoded cluster is requested in advance to reduce segment-boundary stalls; the cache is replaced or invalidated on navigation and never grows into whole-file buffering. Each cluster is limited to 16 MiB of encoded video and 8 MiB of encoded audio; decoded audio is limited to 32 MiB. Video frames are decoded sequentially and painted to one canvas.

Opus packets are decoded by a selectively packaged libopus WebAssembly runtime because the supported Electron baseline advertises AudioDecoder capability but rejects actual packets. Vorbis packets use WebCodecs after validating and copying their bounded Xiph-laced initialization data; deterministic Extension Host coverage requires actual decoded output because the runtime's capability probe can overstate usable configurations. omnifile.video.hardwareAcceleration lets users retain the runtime default or prefer hardware/software decoding. The preference is verified by an actual frame decode and falls back through safe alternatives; diagnostics report the accepted preference without claiming that the browser exposed its physical decoder. Sequential clusters retain Opus decoder state, while explicit cross-cluster seeks reset it; audio-only trailing clusters are accepted without discarding the last displayed frame. When a trusted user gesture permits AudioContext to run, its monotonic clock schedules both PCM buffers and video frames; automatic transitions never retry a blocked resume and therefore cannot stall video-only playback. Pause, seek, mute, cluster replacement, and disposal stop active audio sources and decoder work.

Extension Host tests cover VP8, VP9, and AV1 WebM, restricted VP8 Matroska, bounded chapter navigation, bounded Opus and Vorbis decoding, mute and volume state, pause/resume, playback completion through three clusters, cross-cluster seeking, on-demand timeline thumbnails, trailing audio-only data, a sparse 40 MiB WebM, and actual muted playback through the shared controls for generated AVC/H.264 Baseline with AAC-LC MP4, M4V, and MOV. The Extension Host matrix passes on Windows, Linux/Xvfb, and macOS. Manual validation covers audible Opus/Vorbis fallback output and longer A/V synchronization; Omnifile does not transcode unsupported content.

See TODO.md for the staged roadmap.

Local manual image fixtures can be regenerated with npm run fixtures:image. They are written under src/test/resources/image/ and intentionally remain ignored by Git; deterministic CI fixtures are generated by the test suite itself.

Local WAV, Ogg Vorbis, FLAC, and Ogg Opus compatibility fixtures can be regenerated with npm run fixtures:audio. They are written under src/test/resources/audio/ and remain ignored by Git. Audio unit and Extension Host coverage uses the same deterministic in-code fixtures; Opus remains a negative runtime-compatibility fixture.

Local VP8, VP9, AV1, VP8-with-Opus, and VP8-with-Vorbis WebM fixtures, a restricted VP8 Matroska fixture, and matching WebVTT/SubRip sidecars can be regenerated with npm run fixtures:video. They are written under src/test/resources/video/ and remain ignored by Git. The same small deterministic resources are embedded in the test suite so clean CI checkouts never depend on local media files.

Representative local video files can be measured in the real Extension Host with npm run benchmark:video -- <video-path>. Add --full-playback before the path to validate every playback segment through completion instead of observing one second after the seek. The benchmark reports only format, byte size, dimensions, duration, selected backend, decoder preference, readiness/seek timing, playback progression, and audio backend; it does not print or persist the document path. Playback is muted during the automated observation because a test process cannot validate audible hardware output. The command supports paths containing spaces on Windows, macOS, and Linux and keeps benchmark resources outside the VSIX.

Custom-decoder performance can be measured against ignored local resources with npm run benchmark:image -- <image-path>. The benchmark reports read time, cold and warm decode time, dimensions, and process memory without uploading or persisting document data.

Contributing

We welcome contributions that maintain the architecture and keep behavior testable and local-first. Please read CONTRIBUTING.md before opening a pull request.

Architecture and documentation

The repository includes architecture guidance and decision records in docs, including the renderer model, preview-session lifecycle, and security-oriented webview constraints.

License and publishing

Omnifile is distributed under the MIT license; bundled codecs retain the licenses documented in third-party notices. The release procedure covers clean validation, VSIX generation, SHA-256 verification, tagging, GitHub Releases, and approved manual Marketplace publication. Run npm run release:artifacts to prepare local artifacts, then npm run release:verify to verify their checksum and release notes. Artifact generation does not publish anything.

Support

Use GitHub Issues for bugs and feature requests. See SUPPORT.md for diagnostic steps and SECURITY.md for private vulnerability reporting.