Skip to content

README.md

Latest commit

 

History

History
177 lines (133 loc) · 7.38 KB

README.md

File metadata and controls

177 lines (133 loc) · 7.38 KB

CodecMedia (Work in Progress)

npm version License Node.js npm Java Version

Raw port from Java (incomplete)

CodecMedia is a Node.js port of the original CodecMedia Java engine for media probing, validation, metadata sidecar persistence, audio extraction, playback workflow simulation, and conversion routing.

Project Status (Important)

  • Current npm release: 1.1.5
  • This npm package is still in active development and not all media files/formats are supported yet.
  • WebM, WAV, and MP4 support are currently under testing and may change.
  • Conversion/transcoding is not fully supported yet (current routes are limited and mostly placeholder behavior).
  • The Node.js implementation is an incomplete port from the Java version.

CodecMedia Logo

Approaches

  • Zero-Dependency
  • Self-Contained
  • Multi-Platform

Repository Layout

  • src/ contains the Node.js implementation used by this npm package.
  • main/java/ refers to the original Java source layout in the upstream CodecMedia project lineage (not part of this npm package repository).
  • npm publishing is intentionally limited to the Node.js package files (src, README.md, LICENSE).

Features (Current / Experimental)

  • Media engine facade via createDefault()
  • Probing support for:
    • MP3 (available for real-file testing, experimental)
    • OGG/Vorbis/Opus (not ready yet, in progress)
    • WAV (RIFF/RIFX/RF64, robust chunk scanning) (available for real-file testing, experimental)
    • AIFF/AIF/AIFC (COMM-based parsing) (not ready yet, in progress)
    • M4A (MP4 audio profile) (not ready yet, in progress)
    • FLAC (STREAMINFO parsing) (not ready yet, in progress)
    • PNG (available for real-file testing, experimental)
    • JPEG (not ready yet, in progress)
    • WebP (not ready yet, in progress)
    • BMP (not ready yet, in progress)
    • TIFF (not ready yet, in progress)
    • HEIC/HEIF/AVIF (basic BMFF parsing) (not ready yet, in progress)
    • MOV (QuickTime container parsing) (not ready yet, in progress)
    • MP4 (basic ISO BMFF parsing) (available for real-file testing, experimental)
    • WebM (available for real-file testing, experimental)
  • Validation with size limits works; strict parser checks are partial (currently reliable for WebM and WAV, others still evolving)
  • Metadata read/write with sidecar persistence (.codecmedia.properties) is available
  • In-Node extraction workflow is available in limited mode (copy/same-format behavior, no real transcoding)
  • Playback API is available for dry-run; desktop-open backend is optional and environment-dependent
  • Conversion hub routing is implemented via DefaultConversionHub (same-format copy, wav <-> pcm stub, image-to-image via codec registry, unsupported routes throw explicit errors)

Optional External Adapters (Opt-In)

  • Core default behavior is pure Node.js and does not execute external binaries.
  • You can opt in to external adapters by passing options to createDefault(options).
  • Example opt-in capabilities:
    • enableFfprobeEnhancement: true to enrich MOV/MP4/WebM probe output when ffprobe is available.
    • imageToImageTranscodeConverter to inject/override image converter implementation when you need custom behavior.

API Behavior Summary

  • get(input): alias of probe(input) for convenience.
  • probe(input): detects media/container characteristics and returns technical stream info for supported formats.
  • readMetadata(input): returns derived probe metadata plus sidecar entries when present.
  • writeMetadata(input, metadata): validates and writes metadata to a sidecar properties file next to the input.
  • extractAudio(input, outputDir, options): validates audio input and writes extracted output into outputDir.
  • convert(input, output, options): performs routed conversion behavior and enforces overwrite handling.
  • play(input, options): supports dry-run playback and optional system default app launch.
  • validate(input, options): validates existence, max size, and optional strict parser-level checks.

Notes and Limitations

  • Current probing focuses on technical media info (mime/type/streams/basic tags).
  • Probe routing performs a lightweight header-prefix sniff before full decode to reduce unnecessary full-file reads for clearly unsupported/unknown inputs.
  • readMetadata uses sidecar metadata persistence; it is not a full embedded tag extractor (for example ID3 album art/APIC).
  • Audio-to-audio conversion is not implemented yet for real transcode cases (for example mp3 -> ogg).
  • The only temporary audio conversion path is a stub wav <-> pcm route and should be treated as non-final behavior.
  • Same-extension conversion is passthrough copy (reencoded=false) via SameFormatCopyConverter.
  • Image-to-image conversion is routed through ImageTranscodeConverter; PNG codec wiring (png -> png) is available in experimental mode.
  • Unsupported routes (for example video -> audio, video -> video, audio -> image) intentionally throw explicit CodecMediaException messages.
  • Rich MOV/MP4/WebM ffprobe enrichment is disabled by default and must be explicitly enabled.
  • WebM and WAV parsing/probing should be considered experimental while testing is ongoing.
  • For OpenAL workflows that require OGG from MP3 input, use an external transcoder first (for example ffmpeg), then play the produced OGG.

Requirements

  • Node.js 18+
  • npm 9+

Install

npm install codecmedia

Quick Example

import { CodecMedia } from "codecmedia";

const engine = CodecMedia.createDefault({
  enableFfprobeEnhancement: false,
});

const input = "./media/sample.mp4";

const probe = engine.probe(input);
console.log("Probe:", probe);

const validation = engine.validate(input, { strict: true, maxBytes: 500 * 1024 * 1024 });
console.log("Validation:", validation);

const metadata = engine.readMetadata(input);
console.log("Metadata:", metadata);

engine.writeMetadata(input, {
  entries: {
    title: "Demo Title",
    artist: "CodecMedia",
  },
});

const playback = engine.play(input, { dryRun: true, allowExternalApp: false });
console.log("Playback:", playback);

Build & Test

npm test
Latest test result (v1.1.5) — npm test 
PS G:\Projects\Code\Lib\CodecMedia\codecmedia-npm> npm run test

> codecmedia@1.1.5 test
> node --test ./test/*.test.js

ℹ tests 159
ℹ suites 48
ℹ pass 159
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 1875.1237

Conversion pipeline tests are available in test/convert.test.js and are included by the default Node test glob.

Run only conversion tests:

node --test ./test/convert.test.js

License

This project is licensed under the Apache License 2.0.

by TamKungZ_