🎬 Adaptive HLS Transcoder

The intelligent, mobile-aware video transcoding solution for modern applications.

📖 The Story

The Problem

In the era of TikTok, formatting, and high-quality mobile streaming, video is not just 16:9 anymore. Traditional transcoding pipelines are rigid. They blindly apply the same bitrate ladder to every video. If you feed them a vertical (portrait) video, they often:

1. Add ugly black bars (letterboxing).
2. Distort the aspect ratio.
3. Waste bandwidth encoding empty space.

Furthermore, most "easy" solutions lock you into a specific cloud provider (AWS MediaConvert, Azure Media Services) or abstract away too much control, making it impossible to own your storage strategy.

The Solution

Adaptive HLS Transcoder was built to solve this. It is an intelligent wrapper around FFmpeg that "looks" at your video before touching it. It detects the orientation, applies the perfect adaptive bitrate profile (HLS), and outputs standard files that you can host anywhere—S3, Azure Blob, Google Cloud, or even your own Nginx server.

✨ Why This Package?

• 📱 Smart Orientation Detection: Automatically detects if a video is Portrait or Landscape. It adjusts the resolution scaling so your 1080x1920 video stays vertical and crisp.
• ☁️ Cloud Agnostic: We don't force you to use AWS or Azure SDKs. We generate the files locally. You verify them, then You upload them. COMPLETE control.
• ⚡ Optimized Presets: Comes with built-in, industry-standard bitrate ladders for:
  • Portrait: 360x640, 720x1280, 1080x1920
  • Landscape: 640x360, 1280x720, 1920x1080
• 🛠 TypeScript Ready: Written in TypeScript with full type definitions included.

🚀 Installation

npm install adaptive-hls-transcoder

Note: You must have ffmpeg installed on your system, or use @ffmpeg-installer/ffmpeg (which is included as a dependency).

💻 Usage

Basic Example

import { VideoProcessor } from 'adaptive-hls-transcoder';

async function processMyVideo() {
  const result = await VideoProcessor.transcode({
    inputPath: './uploads/user-video.mp4',
    outputDir: './temp/transcoded',
    outputBaseName: 'video_123',
    segmentDuration: 10, // optional, default 10s
  });

  console.log(`✅ Processed ${result.originalOrientation} video!`);
  console.log(`📂 Master Playlist: ${result.masterPlaylistPath}`);

  // result.variants contains the paths to all generated quality levels
  // Ready for you to upload to S3!
}

processMyVideo();

The Output

The transcoder generates a standard HLS structure:

/output
  ├── video_123_master.m3u8       <-- The file you give to your video player
  ├── video_123_800k.m3u8         <-- Low quality variant
  ├── video_123_800_000.ts        <-- Video segments
  ├── video_123_2800k.m3u8        <-- Mid quality variant
  └── ...

🤝 Contributing

We believe in open standards and optimized media. Pull requests are welcome!

1. Fork the repo
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request