PHPackages                             zhitoo/laravel-hls-converter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. zhitoo/laravel-hls-converter

ActiveLibrary[Image & Media](/categories/media)

zhitoo/laravel-hls-converter
============================

Laravel package for converting videos to HLS format using the HLS Converter microservice

v0.1.0(1mo ago)03MITPHPPHP ^8.1

Since Jun 23Pushed 1mo agoCompare

[ Source](https://github.com/zhitoo/laravel-hls-converter)[ Packagist](https://packagist.org/packages/zhitoo/laravel-hls-converter)[ RSS](/packages/zhitoo-laravel-hls-converter/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

Laravel HLS Converter
=====================

[](#laravel-hls-converter)

A Laravel package for converting videos to HLS (HTTP Live Streaming) format via the [HLS Converter microservice](https://github.com/zhitoo/hls-converter).

Requirements
------------

[](#requirements)

- PHP 8.1+
- Laravel 10 or 11
- PHP `zip` extension (for extraction features)

Installation
------------

[](#installation)

```
composer require zhitoo/laravel-hls-converter
```

Publish the config file:

```
php artisan vendor:publish --tag=hls-converter-config
```

Configuration
-------------

[](#configuration)

Add the following to your `.env`:

```
HLS_CONVERTER_BASE_URL=https://hls.yourdomain.com
HLS_CONVERTER_API_KEY=your-secret-api-key
HLS_CONVERTER_TIMEOUT=30
HLS_CONVERTER_DOWNLOAD_TIMEOUT=120

# Optional: temp directory for ZIP download/extract (default: storage/app/hls-temp)
HLS_CONVERTER_TEMP_PATH=/tmp/hls-temp
```

Usage
-----

[](#usage)

### Submit a conversion job

[](#submit-a-conversion-job)

```
use Zhitoo\HlsConverter\Facades\HlsConverter;

$taskId = HlsConverter::convert(
    videoUrl: 'https://example.com/video.mp4',
    resolutions: [1080, 720, 480],   // omit for original quality only
    chunkDuration: 10,
    audioChannels: 2,
);
```

### Check status

[](#check-status)

```
$status = HlsConverter::status($taskId);

echo $status->status;    // Pending | Processing | Completed | Failed
echo $status->progress;  // 0–100

if ($status->isCompleted()) {
    echo $status->masterPlaylist; // "master.m3u8"
    foreach ($status->qualities as $q) {
        echo $q['label'] . ' → ' . $q['playlist'];
        // 720p → 720p/output.m3u8
    }
}
```

### Download ZIP

[](#download-zip)

```
// Save to an explicit path
HlsConverter::downloadToFile($taskId, storage_path("hls/{$taskId}.zip"));

// Or get a PSR-7 stream
$stream = HlsConverter::download($taskId);
file_put_contents(storage_path("hls/{$taskId}.zip"), $stream);
```

### Extract ZIP to a local directory

[](#extract-zip-to-a-local-directory)

Downloads the ZIP, extracts it, deletes the ZIP, and returns the list of extracted file paths.

```
$files = HlsConverter::extractTo($taskId, storage_path("hls/{$taskId}"));

// $files is an array of absolute paths:
// [
//   '/var/www/storage/app/hls//master.m3u8',
//   '/var/www/storage/app/hls//720p/output.m3u8',
//   '/var/www/storage/app/hls//720p/segment_000.ts',
//   ...
// ]
```

### Transfer HLS files to a Laravel storage disk

[](#transfer-hls-files-to-a-laravel-storage-disk)

Downloads the ZIP, extracts it, uploads every file to the chosen storage disk, and cleans up all temp files automatically.

```
// Transfer to a specific disk (local, s3, ftp, etc.)
$result = HlsConverter::transferToStorage(
    taskId: $taskId,
    storagePath: "videos/hls/{$taskId}",
    disk: 's3',
);

// Or use the default filesystem disk
$result = HlsConverter::transferToDefaultStorage(
    taskId: $taskId,
    storagePath: "videos/hls/{$taskId}",
);

echo $result->disk;                  // "s3"
echo $result->basePath;              // "videos/hls/"
echo $result->masterPlaylistPath();  // "videos/hls//master.m3u8"

foreach ($result->files as $path) {
    echo Storage::disk($result->disk)->url($path);
}

// Get as array
$array = $result->toArray();
// [
//   'disk'            => 's3',
//   'base_path'       => 'videos/hls/',
//   'master_playlist' => 'videos/hls//master.m3u8',
//   'files'           => [...],
// ]
```

### Polling until done then transferring

[](#polling-until-done-then-transferring)

```
use Zhitoo\HlsConverter\Facades\HlsConverter;
use Zhitoo\HlsConverter\Exceptions\HlsConverterException;

$taskId = HlsConverter::convert('https://example.com/video.mp4', [720, 480]);

do {
    sleep(5);
    $status = HlsConverter::status($taskId);
} while ($status->isPending() || $status->isProcessing());

if ($status->isFailed()) {
    $log = HlsConverter::logs($taskId);
    throw new \RuntimeException("Conversion failed.\n{$log}");
}

$result = HlsConverter::transferToStorage($taskId, "videos/hls/{$taskId}", 's3');
```

### Dependency injection

[](#dependency-injection)

```
use Zhitoo\HlsConverter\HlsConverter;
use Zhitoo\HlsConverter\DTOs\TransferResult;

class VideoService
{
    public function __construct(private HlsConverter $hls) {}

    public function process(string $url, string $taskId): TransferResult
    {
        return $this->hls->transferToStorage($taskId, "hls/{$taskId}", 's3');
    }
}
```

Exception Handling
------------------

[](#exception-handling)

All methods throw `Zhitoo\HlsConverter\Exceptions\HlsConverterException` on failure.

```
use Zhitoo\HlsConverter\Exceptions\HlsConverterException;

try {
    $result = HlsConverter::transferToStorage($taskId, 'videos/hls', 's3');
} catch (HlsConverterException $e) {
    logger()->error('HLS transfer failed', ['error' => $e->getMessage()]);
}
```

API Reference
-------------

[](#api-reference)

MethodDescriptionReturns`convert($url, $resolutions, $chunkDuration, $audioChannels)`Submit a conversion job`string` task\_id`status($taskId)`Get task status`TaskStatus``logs($taskId)`Get raw FFmpeg log`string``download($taskId)`Get ZIP as a PSR-7 stream`StreamInterface``downloadToFile($taskId, $path)`Save ZIP to a local file`void``extractTo($taskId, $destination)`Download + extract ZIP to a local dir`string[]` file paths`transferToStorage($taskId, $storagePath, $disk)`Download + extract + upload to storage disk`TransferResult``transferToDefaultStorage($taskId, $storagePath)`Same, using `filesystems.default` disk`TransferResult`### `TaskStatus` DTO

[](#taskstatus-dto)

PropertyTypeDescription`taskId`stringTask UUID`status`string`Pending`, `Processing`, `Completed`, `Failed``progress`int0–100`currentStep`stringCurrent processing step`retryCount`intNumber of retries so far`createdAt`stringISO 8601`updatedAt`stringISO 8601`masterPlaylist`string|null`master.m3u8` — only when Completed`qualities`array`[{height, label, playlist}]` — only when CompletedHelper methods: `isPending()`, `isProcessing()`, `isCompleted()`, `isFailed()`

### `TransferResult` DTO

[](#transferresult-dto)

PropertyTypeDescription`disk`stringStorage disk name`basePath`stringBase path inside the disk`masterPlaylist`string|null`master.m3u8` relative name, or null`files`string\[\]Full storage paths of all uploaded filesMethods: `masterPlaylistPath()` — full path including `basePath`, `toArray()`

License
-------

[](#license)

MIT

###  Health Score

34

—

LowBetter than 74% of packages

Maintenance90

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/dd4e246c9db4ab3f4d867ef0c17db91b7ca81ad99ecdb40928e0a6f5668095e1?d=identicon)[zhitoo](/maintainers/zhitoo)

---

Top Contributors

[![zhitoo](https://avatars.githubusercontent.com/u/20835893?v=4)](https://github.com/zhitoo "zhitoo (1 commits)")

---

Tags

laravelvideoffmpegconverterhls

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/zhitoo-laravel-hls-converter/health.svg)

```
[![Health](https://phpackages.com/badges/zhitoo-laravel-hls-converter/health.svg)](https://phpackages.com/packages/zhitoo-laravel-hls-converter)
```

###  Alternatives

[laravel/socialite

Laravel wrapper around OAuth 1 & OAuth 2 libraries.

5.7k113.1M969](/packages/laravel-socialite)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M353](/packages/psalm-plugin-laravel)[intervention/image-laravel

Laravel Integration of Intervention Image

1589.8M212](/packages/intervention-image-laravel)[spatie/laravel-export

Create a static site bundle from a Laravel app

679153.2k6](/packages/spatie-laravel-export)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5222.6k](/packages/simplestats-io-laravel-client)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1239.7k25](/packages/fleetbase-core-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)