> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devdeia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Every Media API method: enhance, diagnose, analyze, analyze speech, analyze music, transcode, and input/output URLs.

All examples assume:

```php theme={null}
use DolbyApi\DolbyApi;

$dolbyApi = new DolbyApi('your-api-token');
```

## Response handling

Every call returns a `DolbyResponse` (a [Saloon](https://docs.saloon.dev/) response), so the usual Saloon response methods are available:

```php theme={null}
$response = $dolbyApi->api('media')->enhanceStatus('job-id');

$response->body();   // raw JSON string
$response->json();   // decoded array
$response->status(); // HTTP status code
```

## Enhance API

Clean up noisy or low-quality audio/video. See the [Enhance API guide](https://docs.dolby.io/media-apis/docs/enhance-api-guide).

```php theme={null}
$startEnhance = $dolbyApi->api('media')->enhance(
    'https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/tunnel.original.mp4',
    'dlb://example_out'
);

$startEnhance->json(); // ["job_id" => "44fccc05-54cc-4bda-84ba-a8c9ee4b8335"]
```

Poll for the result with the job ID:

```php theme={null}
$enhanceStatus = $dolbyApi->api('media')->enhanceStatus('44fccc05-54cc-4bda-84ba-a8c9ee4b8335');
```

## Diagnose API

An automated quality report for a media file. See the [Diagnose API guide](https://docs.dolby.io/media-apis/docs/diagnose-api-guide).

```php theme={null}
$diagnoseResponse = $dolbyApi->api('media')->diagnose(
    'https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/tunnel.original.mp4',
    ['type' => 'mobile_phone']
);

$diagnoseResponse->json(); // ["job_id" => "..."]
```

```php theme={null}
$diagnoseStatusResponse = $dolbyApi->api('media')->diagnoseStatus('job-id');
```

## Analyze API

Loudness and quality analysis against a chosen profile. See the [Analyze API guide](https://docs.dolby.io/media-apis/docs/analyze-api-guide).

```php theme={null}
$loudness = ['profile' => 'service_amazon'];

$analyzeResponse = $dolbyApi->api('media')->analyze(
    'https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/tunnel.original.mp4',
    'dlb://analyze_out',
    $loudness
);
```

```php theme={null}
$analyzeStatusResponse = $dolbyApi->api('media')->analyzeStatus('job-id');
```

<Note>
  `analyze()` also accepts a fourth, optional `$content` array (defaults to `['type' => '']`) for content-type hints.
</Note>

## Analyze Speech and Analyze Music APIs

Speech- and music-specific analysis. Both take a webhook URL to call on completion — see the [Speech Analytics guide](https://docs.dolby.io/media-apis/docs/speech-analytics-api-guide) and [Analyze Music guide](https://docs.dolby.io/media-apis/docs/analyze-music-api-guide).

```php theme={null}
$analyzeSpeechResponse = $dolbyApi->api('media')->analyzeSpeech(
    'https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/tunnel.original.mp4',
    'dlb://analyze_speech_out',
    ['url' => 'https://your-webhook.example.com/']
);

$analyzeSpeechStatusResponse = $dolbyApi->api('media')->analyzeSpeechStatus('job-id');
```

```php theme={null}
$analyzeMusicResponse = $dolbyApi->api('media')->analyzeMusic(
    'https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/tunnel.original.mp4',
    'dlb://analyze_music_out',
    ['url' => 'https://your-webhook.example.com/']
);

$analyzeMusicStatusResponse = $dolbyApi->api('media')->analyzeMusicStatus('job-id');
```

## Transcode API

Convert media between formats and outputs. See the [Transcode API guide](https://docs.dolby.io/media-apis/docs/transcode-api-guide).

```php theme={null}
$inputs = [
    'source' => 'https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/indoors.original.mp4',
];

$outputs = [
    'id' => 'my_mp4',
    'destination' => 'dlb://out/airplane-transcoded.mp4',
    'kind' => 'mp4',
];

$transcodingResponse = $dolbyApi->api('media')->transcode($inputs, $outputs);
```

```php theme={null}
$transcodeResultsResponse = $dolbyApi->api('media')->transcodeResults('job-id');
```

<Note>
  `transcode()` also accepts two further optional arguments: `$storage` and `$onComplete`, both nullable arrays.
</Note>

## Input and Output URLs

Get a signed upload URL for Dolby's storage:

```php theme={null}
$uploadUrl = $dolbyApi->api('media')->getUploadUrl('dlb://input/file.wav');
```

Get a signed download URL:

```php theme={null}
$downloadUrl = $dolbyApi->api('media')->getDownloadUrl('dlb://example_out');
```

## Error handling

Errors come back as a [Problem Details](https://www.rfc-editor.org/rfc/rfc7807) style response:

```php theme={null}
[
    'type' => '/problems/validation-error',
    'title' => "Your request parameters didn't validate",
    'status' => 400,
    'instance' => '/media/output',
    'detail' => 'Request body contains invalid json',
]
```

Check `$response->status()` before trusting `$response->json()`.