Initial import

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: Synchro
+patreon: marcusbointon

.github/workflows/tests.yml

@@ -0,0 +1,72 @@
+name: Tests
+
+on: ['push', 'pull_request']
+
+jobs:
+  coding-standards:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest]
+        php: [7.4]
+        dependency-version: [prefer-stable]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer update --${{ matrix.dependency-version }} --no-interaction --no-progress
+
+      - name: Check coding standards
+        run: vendor/bin/phpcs
+
+  tests:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        php: [7.3, 7.4, 8.0]
+        dependency-version: [prefer-lowest, prefer-stable]
+
+    name: Tests P${{ matrix.php }} - ${{ matrix.os }} - ${{ matrix.dependency-version }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Cache dependencies
+        uses: actions/cache@v1
+        with:
+          path: ~/.composer/cache/files
+          key: dependencies-php-${{ matrix.php }}-composer-${{ hashFiles('composer.json') }}
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer:v2
+          coverage: pcov
+
+      - name: Install PHP 7 dependencies
+        run: composer update --${{ matrix.dependency-version }} --no-interaction --no-progress
+        if: "matrix.php < 8"
+
+      - name: Install PHP 8 dependencies
+        run: composer update --${{ matrix.dependency-version }} --ignore-platform-req=php --no-interaction --no-progress
+        if: "matrix.php >= 8"
+
+      - name: Pest Unit Tests
+        run: vendor/bin/pest --colors=always
+
+      - name: PHPStan Type Checks
+        run: vendor/bin/phpstan analyse --ansi --no-progress --memory-limit=0
+
+      - name: Psalm Type Tests
+        run: vendor/bin/psalm --shepherd --show-info=true -c psalm.xml

.gitignore

@@ -0,0 +1,4 @@
+vendor/
+composer.lock
+.phpcs-cache
+.phpunit.result.cache

.phpcs.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:noNamespaceSchemaLocation="vendor/squizlabs/php_codesniffer/phpcs.xsd">
+
+  <config name="testVersion" value="7.4-"/>
+
+  <arg name="basepath" value="."/>
+  <arg name="cache" value=".phpcs-cache"/>
+  <arg name="colors"/>
+  <arg name="extensions" value="php"/>
+  <arg name="parallel" value="10"/>
+  <!-- Show progress -->
+  <arg value="p"/>
+
+  <file>src</file>
+  <file>tests</file>
+
+  <rule ref="PSR12"/>
+  <rule ref="PHPCompatibility"/>
+</ruleset>

LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Marcus Bointon <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,42 @@
+# Audio File Thumbnail Generator for Spatie's Laravel Media Library
+
+This audio image generator generates thumbnails for audio files uploaded through Spatie's Media Library, just as it already does for image, video, and PDF formats.
+Thumbnails of a mono waveform of the whole audio file are generated using ffmpeg's `waveform` converter. It uses the same [PHP FFMpeg package](https://packagist.org/packages/php-ffmpeg/php-ffmpeg) that is used for the video formats already supported by Media Library, so there are no additional dependencies.
+
+## Installation & configuration
+Install Spatie's Media Library (version 9.1.0 or later) in your project. This will generate a config file in `config/media-library.php`. Add the audio waveform generator to the list of generators in the `image_generators` section, including optionally setting default `width`, `height`, `foreground` and `background` properties (default values shown):
+
+```php
+'image_generators' => [
+    ...,
+    Synchro\MediaLibrary\Conversions\ImageGenerators\AudioWaveform::class => [
+        'width' => 2048,
+        'height' => 2048,
+        'foreground' => '#113554',
+        'background' => '#CBE2F4',
+    ]
+],
+```
+
+These parameters are optional - you can leave them out if you're happy with the defaults.
+
+## Thumbnail colours
+The waveform is drawn in the foreground colour, over the background colour. Both should be specified using standard HTML 6-digit hex values passed through the media library config, as above.
+
+## Thumbnail sizing
+The base size of the thumbnails can be set via the media library config, as shown above. The default is 2048 x 2048 pixels, neutral values chosen because audio files have no inherent size or aspect ratio. This is quite large, but since the images are very simple, they will compress very well in PNG format.
+This size doesn't directly affect the thumbnails delivered to clients because media library itself generates scaled-down versions to match client requests, however, it does have a direct effect on the aspect ratio of the thumbnails, so if you want a 16:9 ratio, change the height to `1152`, or `1536` for 4:3. 
+
+## Supported formats
+
+* `aiff`
+* `flac`
+* `m4a`
+* `mp3`
+* `mp4`
+* `ogg`
+* `wav`
+* `wma`
+
+## Running tests
+Tests are written in pest, so to run the test suite, install dev dependencies (`composer install --dev`) and then run `./vendor/bin/pest`. There are also configurations for phpcs, psalm, and phpstan to check code style and type coverage, or run all of them using `composer test`.

composer.json

@@ -0,0 +1,51 @@
+{
+  "name": "synchro/laravel-medialibrary-audio",
+  "description": "Audio file thumbnail generator for Spatie's Laravel Media Library",
+  "authors": [
+    {
+      "name": "Marcus Bointon",
+      "email": "[email protected]"
+    }
+  ],
+  "keywords": [
+    "laravel-medialibrary",
+    "media",
+    "conversion",
+    "audio",
+    "laravel"
+  ],
+  "homepage": "https://github.com/spatie/laravel-medialibrary",
+  "minimum-stability": "stable",
+  "license": "MIT",
+  "require": {
+    "php": "^7.4|^8.0",
+    "spatie/laravel-medialibrary": "^9.1.0"
+  },
+  "require-dev": {
+    "pestphp/pest": "^v0.3.10",
+    "php-ffmpeg/php-ffmpeg": "^0.16.0",
+    "laravel/framework": "^8.0",
+    "dealerdirect/phpcodesniffer-composer-installer": "^0.7",
+    "phpcompatibility/php-compatibility": "^9.3.5",
+    "phpstan/phpstan": "^0.12.50",
+    "squizlabs/php_codesniffer": "^3.5.8",
+    "vimeo/psalm": "^4.0.1"
+  },
+  "autoload": {
+    "psr-4": {
+      "Synchro\\MediaLibrary\\Conversions\\ImageGenerators\\": "src"
+    }
+  },
+  "scripts": {
+    "test:cs": "./vendor/bin/phpcs",
+    "test:unit": "./vendor/bin/pest --coverage --colors=always",
+    "test:types": "./vendor/bin/phpstan analyse --ansi --no-progress --memory-limit=0",
+    "test:psalm": "./vendor/bin/psalm --show-info=true",
+    "test": [
+      "@test:cs",
+      "@test:unit",
+      "@test:types",
+      "@test:psalm"
+    ]
+  }
+}

phpstan.neon.dist

@@ -0,0 +1,6 @@
+parameters:
+    level: 7
+    paths:
+        - src
+        - tests
+    checkMissingIterableValueType: false

phpunit.xml.dist

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="vendor/autoload.php" backupGlobals="false" backupStaticAttributes="false" colors="true" verbose="true" convertErrorsToExceptions="true" convertNoticesToExceptions="true" convertWarningsToExceptions="true" processIsolation="false" stopOnFailure="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+  <coverage>
+    <include>
+      <directory suffix=".php">src/</directory>
+    </include>
+  </coverage>
+  <testsuites>
+    <testsuite name="Synchro Test Suite">
+      <directory>tests</directory>
+    </testsuite>
+  </testsuites>
+</phpunit>

psalm.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<psalm
+    errorLevel="2"
+    resolveFromConfigFile="true"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+>
+    <projectFiles>
+        <directory name="src" />
+        <ignoreFiles>
+            <directory name="vendor" />
+        </ignoreFiles>
+    </projectFiles>
+</psalm>

src/AudioWaveform.php

@@ -0,0 +1,106 @@
+<?php
+
+namespace Synchro\MediaLibrary\Conversions\ImageGenerators;
+
+use FFMpeg\FFMpeg;
+use Illuminate\Support\Collection;
+use Spatie\MediaLibrary\Conversions\Conversion;
+use Spatie\MediaLibrary\Conversions\ImageGenerators\ImageGenerator;
+use Spatie\MediaLibrary\Support\ImageFactory;
+
+class AudioWaveform extends ImageGenerator
+{
+    private int $width = 2048;
+    private int $height = 2048;
+    private string $foreground = '#113554';
+    private string $background = '#CBE2F4';
+
+    public function __construct(array $args = [])
+    {
+        //Validate width and height
+        if (array_key_exists('width', $args) && (int)$args['width'] > 0 && (int)$args['width'] <= 8192) {
+            $this->width = (int)$args['width'];
+        }
+        if (array_key_exists('height', $args) && (int)$args['height'] > 0 && (int)$args['height'] <= 8192) {
+            $this->height = (int)$args['height'];
+        }
+        //Validate colours
+        if (array_key_exists('foreground', $args) && preg_match('/^#[A-Fa-f0-9]{6}$/', (string)$args['foreground'])) {
+            $this->foreground = (string)$args['foreground'];
+        }
+        if (array_key_exists('background', $args) && preg_match('/^#[A-Fa-f0-9]{6}$/', (string)$args['background'])) {
+            $this->background = (string)$args['background'];
+        }
+    }
+
+    public function convert(string $file, Conversion $conversion = null): string
+    {
+        $imageFile = pathinfo($file, PATHINFO_DIRNAME) . '/' . pathinfo($file, PATHINFO_FILENAME) . '.png';
+
+        $ffmpeg = FFMpeg::create(
+            [
+                'ffmpeg.binaries'  => config('media-library.ffmpeg_path'),
+                'ffprobe.binaries' => config('media-library.ffprobe_path'),
+            ]
+        );
+
+        $audio = $ffmpeg->open($file);
+        //This generates a waveform image drawn with the foreground colour on a transparent background
+        $waveform = $audio->waveform(
+            $this->width,
+            $this->height,
+            [$this->foreground]
+        );
+        $waveform->save($imageFile);
+
+        //Read the file back in again so we can fill in the background colour
+        $image = ImageFactory::load($imageFile);
+        //This function wants a hex colour without a # prefix, will also work with HTML named colours like 'pink'
+        $image->background(str_replace('#', '', $this->background));
+        $image->optimize();
+        $image->save($imageFile);
+
+        return $imageFile;
+    }
+
+    public function requirementsAreInstalled(): bool
+    {
+        return class_exists('\\FFMpeg\\FFMpeg');
+    }
+
+    public function supportedExtensions(): Collection
+    {
+        return collect(
+            [
+                'aac',
+                'aif',
+                'aifc',
+                'aiff',
+                'flac',
+                'm4a',
+                'mp3',
+                'mp4',
+                'ogg',
+                'wav',
+                'wma',
+            ]
+        );
+    }
+
+    public function supportedMimeTypes(): Collection
+    {
+        return collect(
+            [
+                'audio/aac',
+                'audio/flac',
+                'audio/mp4',
+                'audio/mpeg3',
+                'audio/ogg',
+                'audio/vnd.wav',
+                'audio/x-aiff',
+                'audio/x-flac',
+                'video/x-ms-asf',
+            ]
+        );
+    }
+}

tests/AudioWaveformTests.php

@@ -0,0 +1,9 @@
+<?php
+
+ it('converts an mp3 file', function () {
+     $sourceBase = __DIR__ . '/testfiles/test.';
+     $audioFile = $sourceBase . 'mp3';
+     $gen = new \Synchro\MediaLibrary\Conversions\ImageGenerators\AudioWaveform();
+     $thumbPath = $gen->convert($audioFile);
+     expect($thumbPath)->toEqual($sourceBase . 'png');
+ });