PHPackages                             mohamed-adel/audio-waveform - 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. [Utility & Helpers](/categories/utility)
4. /
5. mohamed-adel/audio-waveform

ActiveLibrary[Utility & Helpers](/categories/utility)

mohamed-adel/audio-waveform
===========================

Audio waveform generator on PHP with SoX

020PHP

Since Feb 13Pushed 2y ago1 watchersCompare

[ Source](https://github.com/M-0x4D/Audio-To-Wave-Image)[ Packagist](https://packagist.org/packages/mohamed-adel/audio-waveform)[ RSS](/packages/mohamed-adel-audio-waveform/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Audio waveform generator on PHP with SoX
========================================

[](#audio-waveform-generator-on-php-with-sox)

[![Example result](example.png)](example.png)

Install
-------

[](#install)

Install SoX and some of its handlers for different audio formats. Also you need a `GD` module or other extension providing `imagecreatetruecolor()` functionality. For example, on Ubuntu:

```
sudo apt install sox libsox-fmt-all
sudo apt install php-gd
```

Install this package using the [Composer](https://getcomposer.org) `require` command:

```
composer require maximal/audio-waveform '~1.0'
```

or add the package name to the `require` section in your `composer.json` file:

```
"require": {
	"maximal/audio-waveform": "~1.0"
}
```

and then run:

```
composer update
```

Use
---

[](#use)

In your PHP source:

```
// Include `maximal\audio` namespace
use maximal\audio\Waveform;

// Open an audio file `track.mp3`
$waveform = new Waveform('track.mp3');

// Save its waveform to the `thumbnail.png` image file which size is 1024×512 pixels
$success = $waveform->getWaveform('thumbnail.png', 1024, 512);
```

### One Phase

[](#one-phase)

To get positive waveform only (i.e. one phase) pass `onePhase` parameter set to `true`:

```
$waveform->getWaveform('one-phase.png', 800, 400, true);
```

Stereo source:

[![One phase stereo](one-phase-stereo.png)](one-phase-stereo.png)

Mono source:

[![One phase stereo](one-phase-mono.png)](one-phase-mono.png)

Settings
--------

[](#settings)

All settings are public static members of `Waveform` class:

- `$linesPerPixel` is the count of lines per each pixel in horizontal axis. Default is `8`.
- `$samplesPerLine` is the count of samples per each line. Default is `512`.
- `$color` is the color of each line. Default is `[95, 95, 95, 0.5]` meaning the dark grey color with 50% opacity.
- `$backgroundColor` is the background color of the waveform file. Default is `[245, 245, 245, 1]` meaning the light grey opaque background with 100% opacity.
- `$axisColor` is the color of each axis. Default is `[0, 0, 0, 0.15]` meaning the black color with 15% opacity.

Examples
--------

[](#examples)

Red waveform with half-transparent peaks:

```
$waveform = new Waveform('track.mp3');
Waveform::$color = [255, 0, 0, 0.5];
$success = $waveform->getWaveform('thumbnail.png', 1024, 512);
```

Red waveform and fully transparent background:

```
$waveform = new Waveform('track.mp3');
Waveform::$color = [255, 0, 0, 0.5];
Waveform::$backgroundColor = [0, 0, 0, 0];
$success = $waveform->getWaveform('thumbnail.png', 1024, 512);
```

Ubuntu Linux thumbnailer for Nautilus file explorer
---------------------------------------------------

[](#ubuntu-linux-thumbnailer-for-nautilus-file-explorer)

1. Install the package to some directory. For example: `/opt/maximal/audio-waveform-php`
2. Place the following code in the file `/usr/share/thumbnailers/waveform.thumbnailer`

    ```
    [Thumbnailer Entry]
    Exec=/opt/maximal/audio-waveform-php/thumbnailer.php %i %o %sx%s
    MimeType=audio/wave;audio/x-wav;audio/mpeg;audio/ogg

    ```

    This repository contains an example thumbnailer file. See: `usr/share/thumbnailers/waveform.thumbnailer`.

    Also you can add other MIME types to the `MimeType` section of your thumbnaler file as long as they are supportable by [SoX](http://sox.sourceforge.net) utility.
3. Clear thumbnail cache and restart Nautilus:

    ```
    rm  -rf  ~/.thumbnails
    nautilus  -q
    ```
4. Since then all your audio files with specified MIME types will be shown in Nautilus using its small waveforms. By default they are WAV, MP3 and OGG files.

Integration with other libraries (e.g. wavesurfer.js)
-----------------------------------------------------

[](#integration-with-other-libraries-eg-wavesurferjs)

`Waveform` class has `getWaveformData()` method for retrieving the waveform data without generating the image. You can use it to integrate with different libraries, for instance, with the great [wavesurfer.js](https://wavesurfer-js.org/).

```
$waveform = new Waveform('track.mp3');
$width = 1024;
$data = $waveform->getWaveformData($width);
// $data['lines1'] and $data['lines2'] now have the waveform data for channels 1 and 2
```

To get positive values only (i.e. one phase) pass `onePhase` parameter set to `true`:

```
$data = $waveform->getWaveformData($width, true);
```

Contact the author
------------------

[](#contact-the-author)

- Website:  (Russian)
- Sijeko Company:  (web, mobile, desktop applications development and graphic design)
- Personal GitHub:
- Company’s GitHub:

###  Health Score

14

—

LowBetter than 2% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity19

Early-stage or recently created project

 Bus Factor1

Top contributor holds 68.4% 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/ae96c956b1920cd35d297bee3142ee4474be09707b1add34d35db7d26380b630?d=identicon)[M-0x4D](/maintainers/M-0x4D)

---

Top Contributors

[![maximal](https://avatars.githubusercontent.com/u/980679?v=4)](https://github.com/maximal "maximal (13 commits)")[![M-0x4D](https://avatars.githubusercontent.com/u/56012558?v=4)](https://github.com/M-0x4D "M-0x4D (4 commits)")[![bradley-varol](https://avatars.githubusercontent.com/u/19194140?v=4)](https://github.com/bradley-varol "bradley-varol (1 commits)")[![netTrekfd](https://avatars.githubusercontent.com/u/6525783?v=4)](https://github.com/netTrekfd "netTrekfd (1 commits)")

### Embed Badge

![Health badge](/badges/mohamed-adel-audio-waveform/health.svg)

```
[![Health](https://phpackages.com/badges/mohamed-adel-audio-waveform/health.svg)](https://phpackages.com/packages/mohamed-adel-audio-waveform)
```

###  Alternatives

[spiral/mcp-server

Spiral bridge for MCP server

541.1k2](/packages/spiral-mcp-server)

PHPackages © 2026

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