feat: extend Audio content for data urls and raw data (#250)

Author: chr-hertel

README.md

@@ -521,7 +521,7 @@ use PhpLlm\LlmChain\Model\Message\MessageBag;
 $messages = new MessageBag(
     Message::ofUser(
         'What is this recording about?',
-        new Audio(dirname(__DIR__).'/tests/Fixture/audio.mp3'), // Path to an audio file
+        Audio:fromFile(dirname(__DIR__).'/tests/Fixture/audio.mp3'), // Path to an audio file
     ),
 );
 $response = $chain->call($messages);

examples/audio-describer.php

@@ -23,7 +23,7 @@
 $messages = new MessageBag(
     Message::ofUser(
         'What is this recording about?',
-        new Audio(dirname(__DIR__).'/tests/Fixture/audio.mp3'),
+        Audio::fromFile(dirname(__DIR__).'/tests/Fixture/audio.mp3'),
     ),
 );
 $response = $chain->call($messages);

src/Model/Message/Content/Audio.php

@@ -6,29 +6,50 @@
 
 use PhpLlm\LlmChain\Exception\InvalidArgumentException;
 
+use function Symfony\Component\String\u;
+
 final readonly class Audio implements Content
 {
     public function __construct(
-        public string $path,
+        public string $data,
+        public string $format,
     ) {
-        if (!is_readable($path) || false === file_get_contents($path)) {
-            throw new InvalidArgumentException(sprintf('The file "%s" does not exist or is not readable.', $path));
+    }
+
+    public static function fromDataUrl(string $dataUrl): self
+    {
+        if (!str_starts_with($dataUrl, 'data:audio/')) {
+            throw new InvalidArgumentException('Invalid audio data URL format.');
         }
+
+        return new self(
+            u($dataUrl)->after('base64,')->toString(),
+            u($dataUrl)->after('data:audio/')->before(';base64,')->toString(),
+        );
+    }
+
+    public static function fromFile(string $filePath): self
+    {
+        if (!is_readable($filePath) || false === $audioData = file_get_contents($filePath)) {
+            throw new InvalidArgumentException(sprintf('The file "%s" does not exist or is not readable.', $filePath));
+        }
+
+        return new self(
+            base64_encode($audioData),
+            pathinfo($filePath, PATHINFO_EXTENSION)
+        );
     }
 
     /**
      * @return array{type: 'input_audio', input_audio: array{data: string, format: string}}
      */
     public function jsonSerialize(): array
     {
-        $data = file_get_contents($this->path);
-        $format = pathinfo($this->path, PATHINFO_EXTENSION);
-
         return [
             'type' => 'input_audio',
             'input_audio' => [
-                'data' => base64_encode($data),
-                'format' => $format,
+                'data' => $this->data,
+                'format' => $this->format,
             ],
         ];
     }

tests/Model/Message/Content/AudioTest.php

@@ -16,45 +16,85 @@
 final class AudioTest extends TestCase
 {
     #[Test]
-    public function constructWithValidPath(): void
+    public function constructWithValidData(): void
     {
-        $audio = new Audio(dirname(__DIR__, 3).'/Fixture/audio.mp3');
+        $audio = new Audio('base64data', 'mp3');
 
-        self::assertSame(dirname(__DIR__, 3).'/Fixture/audio.mp3', $audio->path);
+        self::assertSame('base64data', $audio->data);
+        self::assertSame('mp3', $audio->format);
     }
 
     #[Test]
-    #[DataProvider('provideValidPaths')]
-    public function jsonSerializeWithValid(string $path, array $expected): void
+    public function fromDataUrlWithValidUrl(): void
     {
-        $audio = new Audio($path);
+        $dataUrl = 'data:audio/mp3;base64,SUQzBAAAAAAAfVREUkMAAAAMAAADMj';
+        $audio = Audio::fromDataUrl($dataUrl);
 
-        $expected = [
-            'type' => 'input_audio',
-            'input_audio' => $expected,
-        ];
-
-        $actual = $audio->jsonSerialize();
+        self::assertSame('SUQzBAAAAAAAfVREUkMAAAAMAAADMj', $audio->data);
+        self::assertSame('mp3', $audio->format);
+    }
 
-        // shortening the base64 data
-        $actual['input_audio']['data'] = substr($actual['input_audio']['data'], 0, 30);
+    #[Test]
+    public function fromDataUrlWithInvalidUrl(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Invalid audio data URL format.');
 
-        self::assertSame($expected, $actual);
+        Audio::fromDataUrl('invalid-url');
     }
 
-    public static function provideValidPaths(): \Generator
+    #[Test]
+    public function fromFileWithValidPath(): void
     {
-        yield 'mp3' => [dirname(__DIR__, 3).'/Fixture/audio.mp3', [
-            'data' => 'SUQzBAAAAAAAfVREUkMAAAAMAAADMj', // shortened
-            'format' => 'mp3',
-        ]];
+        $audio = Audio::fromFile(dirname(__DIR__, 3).'/Fixture/audio.mp3');
+
+        self::assertSame('mp3', $audio->format);
+        self::assertNotEmpty($audio->data);
     }
 
     #[Test]
-    public function constructWithInvalidPath(): void
+    public function fromFileWithInvalidPath(): void
     {
+        $this->expectException(\InvalidArgumentException::class);
         $this->expectExceptionMessage('The file "foo.mp3" does not exist or is not readable.');
 
-        new Audio('foo.mp3');
+        Audio::fromFile('foo.mp3');
+    }
+
+    #[Test]
+    #[DataProvider('provideAudioData')]
+    public function jsonSerializeReturnsCorrectFormat(string $data, string $format, array $expected): void
+    {
+        $audio = new Audio($data, $format);
+        $actual = $audio->jsonSerialize();
+
+        self::assertSame($expected, $actual);
+    }
+
+    public static function provideAudioData(): \Generator
+    {
+        yield 'mp3 data' => [
+            'SUQzBAAAAAAAfVREUkMAAAAMAAADMj',
+            'mp3',
+            [
+                'type' => 'input_audio',
+                'input_audio' => [
+                    'data' => 'SUQzBAAAAAAAfVREUkMAAAAMAAADMj',
+                    'format' => 'mp3',
+                ],
+            ],
+        ];
+
+        yield 'wav data' => [
+            'UklGRiQAAABXQVZFZm10IBA=',
+            'wav',
+            [
+                'type' => 'input_audio',
+                'input_audio' => [
+                    'data' => 'UklGRiQAAABXQVZFZm10IBA=',
+                    'format' => 'wav',
+                ],
+            ],
+        ];
     }
 }

tests/Model/Message/UserMessageTest.php

@@ -52,7 +52,7 @@ public function hasAudioContentWithoutAudio(): void
     #[Test]
     public function hasAudioContentWithAudio(): void
     {
-        $message = new UserMessage(new Text('foo'), new Audio(dirname(__DIR__, 2).'/Fixture/audio.mp3'));
+        $message = new UserMessage(new Text('foo'), Audio::fromFile(dirname(__DIR__, 2).'/Fixture/audio.mp3'));
 
         self::assertTrue($message->hasAudioContent());
     }