PHPackages                             streams-sro/gaston - 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. [Localization & i18n](/categories/localization)
4. /
5. streams-sro/gaston

ActiveLibrary[Localization & i18n](/categories/localization)

streams-sro/gaston
==================

PHP client for the Gaston API (transcription, translation and sentence search).

v0.6.0(1mo ago)03↓50%MITPHPPHP >=7.0

Since Jun 28Pushed 1mo agoCompare

[ Source](https://github.com/streams-sro/gaston-php)[ Packagist](https://packagist.org/packages/streams-sro/gaston)[ Docs](https://gaston.live)[ RSS](/packages/streams-sro-gaston/feed)WikiDiscussions master Synced 2w ago

READMEChangelogDependencies (2)Versions (4)Used By (0)

Gaston API Client (PHP)
=======================

[](#gaston-api-client-php)

A small, dependency-free PHP client for the **Gaston API**: transcription, translation and full-text search of sentences within transcribed recordings.

> Requires a Gaston account and an API token (see [Configuration](#configuration)).

This is a PHP port of the [official Python client](https://pypi.org/project/gaston/)and tracks the same API.

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

[](#requirements)

- PHP **7.0+**
- The `curl` and `json` extensions (both bundled with PHP by default)

No third-party runtime dependencies.

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

[](#installation)

```
composer require streams-sro/gaston
```

Quick start
-----------

[](#quick-start)

```
use StreamsSro\Gaston\GastonClient;

$client = new GastonClient('gapi-...');

// Who am I + remaining quota
$me = $client->me();
echo $me->email, ' files left: ', $me->usage->filesLeft, PHP_EOL;

// Transcribe a local file
$result = $client->transcribe('interview.mp4', 'en', null, 'My interview');
echo $result->id, ' ', $result->state, PHP_EOL;

// Transcribe from a URL (YouTube or web)
$client->transcribeUrl('https://youtu.be/dQw4w9WgXcQ', 'en');

// Translate an existing transcription
$client->translate($result->id, 'de');

// Word-level alignment of a translation against source timestamps
// (requires a completed translation in that language)
$client->alignTranslation($result->id, 'de', true);

// Speaker diarization (requires a completed translation in that language)
$client->diarize($result->id, 'de', 2);

// Fetch a media item with its sentences
$media = $client->getMedia($result->id, 'en');
foreach ($media->sentences as $sentence) {
    echo $sentence->id, ' ', $sentence->getText(), ' ', $sentence->speaker, PHP_EOL;
}

// Full text search across the whole library
$results = $client->search('climate change', 0, 20);
echo 'total matches: ', $results->total, PHP_EOL;
foreach ($results as $hit) {
    echo $hit['_sentence']['body'], ' -> ', implode(' ', $hit['_highlight']['body']), PHP_EOL;
}
```

The constructor signature is:

```
new GastonClient(
    string $token = null,          // falls back to GASTON_API_TOKEN
    float  $timeout = 30.0,         // ordinary requests, seconds (0 = no limit)
    float  $uploadTimeout = 600.0,  // file-upload endpoint, seconds
    float  $connectTimeout = 10.0,  // connection timeout, seconds
    HttpClientInterface $httpClient = null
);
```

### Configuration

[](#configuration)

Generate an API token in the Gaston app under [Settings -> API](https://www.gaston.live/user/settings/api/en). Full endpoint documentation is available at .

The token can be supplied directly or via the `GASTON_API_TOKEN` environment variable:

ArgumentEnvironment variableDefault`$token``GASTON_API_TOKEN`(required)```
// Uses GASTON_API_TOKEN from the environment
$client = new GastonClient();
```

### Timeouts

[](#timeouts)

Ordinary requests use a 30s timeout. The file upload in `transcribe()` can take minutes for large files, so it uses a separate, more generous `$uploadTimeout`(default 600s). All timeouts are in seconds; pass `0` to wait indefinitely.

```
// Customise the defaults for all calls
$client = new GastonClient('gapi-...', 30.0, 1800.0); // up to 30 min uploads

// Or override per call (e.g. no timeout for a very large file)
$client->transcribe('huge-recording.mp4', null, null, null, 0.0);
```

`transcribe()` accepts either a file path or an open stream resource:

```
$fh = fopen('interview.mp4', 'rb');
$client->transcribe($fh, 'en');
```

Directories
-----------

[](#directories)

```
$folder = $client->createDirectory('Podcasts');
$client->updateDirectory($folder->id, 'Podcast archive');
$moved = $client->moveMedia('me...', $folder->id); // returns the updated Media
$tree = $client->directoryTree();
$client->deleteDirectory($folder->id);
```

Search
------

[](#search)

`$client->search($query, $from = 0, $max = 50, $dirIds = null, $lang = null, $mediaId = null)`runs a full-text search over every sentence in your transcribed media.

### Query syntax

[](#query-syntax)

The query supports a subset of the Lucene `query_string` syntax:

FeatureExampleNotesBoolean `AND``cats AND dogs`both terms must appearBoolean `OR``cats OR dogs`either termBoolean `NOT``cats NOT dogs`exclude a termGrouping`(cats OR dogs) AND vet`combine operators with parenthesesExact phrase`"climate change"`quoted terms match as a phraseTrailing wildcard`transcri*`matches `transcribe`, `transcription`...Leading wildcards (`*tion`), field selectors, fuzzy (`~`), boosts (`^`) and ranges are not supported and are stripped server-side. Queries must be at least 3 characters.

```
$results = $client->search('(invoice OR receipt) AND "due date" NOT draft');
```

### Filtering and pagination

[](#filtering-and-pagination)

```
// Search within a single directory
$client->search('budget', 0, 50, [42]);

// Search across several directories
$client->search('budget', 0, 50, [42, 43, 7]);

// Restrict to one language, and page through results
$page2 = $client->search('budget', 50, 50, null, 'en');

// Search within a single media
$client->search('budget', 0, 50, null, null, 'me...');
```

### Reading results

[](#reading-results)

`search()` returns a `SearchResults` object. Iterate it for hits, or read `->total` for the overall match count. Each hit is an array with:

- `_sentence` - the matched sentence plus its `media` metadata (id, title, duration, directory, thumbnail, file, originUrl).
- `_highlight` - matched fragments with the hit terms wrapped in `...` tags.

```
$results = $client->search('climate change', 0, 20);
echo 'total matches: ', $results->total, PHP_EOL;
foreach ($results as $hit) {
    $sentence = $hit['_sentence'];
    echo $sentence['media']['title'], ' | ', implode(' ', $hit['_highlight']['body']), PHP_EOL;
}
```

Error handling
--------------

[](#error-handling)

All failures throw a subclass of `GastonException`:

```
use StreamsSro\Gaston\Exception\AuthenticationException;
use StreamsSro\Gaston\Exception\NotFoundException;
use StreamsSro\Gaston\Exception\RateLimitException;

try {
    $client->transcribe('clip.mp4');
} catch (RateLimitException $e) {
    echo 'File limit reached';
} catch (AuthenticationException $e) {
    echo 'Bad token / disabled account';
} catch (NotFoundException $e) {
    echo 'Not found: ', $e->getMessage();
}
```

ExceptionTrigger`AuthenticationException`HTTP 403, invalid token / disabled user`BadRequestException`HTTP 400, invalid parameters`NotFoundException`HTTP 404, resource not found`RateLimitException`HTTP 429, usage limit exceeded`ExternalServiceException`HTTP 502, an external dependency failed upstream`GastonApiException`any other API errorEvery API exception carries `->getStatusCode()`, `->getMessage()`, `->getDetails()` and the raw `->getPayload()`. `GastonException` is the base class for all of the above (including transport-level failures).

Supported languages
-------------------

[](#supported-languages)

```
use StreamsSro\Gaston\Languages;

Languages::SUPPORTED;                  // transcription source languages
Languages::translationLanguages();     // available translation targets
Languages::isSupported('en');          // bool
Languages::isTranslationTarget('de');  // bool
```

Development
-----------

[](#development)

The test suite uses PHPUnit (a dev-only dependency; the library itself has none):

```
composer install
composer test
```

License
-------

[](#license)

MIT - see [LICENSE](LICENSE).

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance93

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity21

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

Every ~4 days

Total

3

Last Release

36d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ac3b1d31d3b1390a9915dcff9471f6c7f5c2e29c1a8c71536569efc6d4a8a03d?d=identicon)[streams-sro](/maintainers/streams-sro)

---

Top Contributors

[![stromajer](https://avatars.githubusercontent.com/u/9317212?v=4)](https://github.com/stromajer "stromajer (3 commits)")

---

Tags

translationapi clientTranscriptionspeech-to-textgaston

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/streams-sro-gaston/health.svg)

```
[![Health](https://phpackages.com/badges/streams-sro-gaston/health.svg)](https://phpackages.com/packages/streams-sro-gaston)
```

###  Alternatives

[gettext/gettext

PHP gettext manager

70233.3M127](/packages/gettext-gettext)[inpsyde/multilingual-press

Simply THE multisite-based free open source plugin for your multilingual websites.

2414.0k1](/packages/inpsyde-multilingual-press)[wcm/wcm-lang-switch

Adds a button to the admin toolbar. This buttons allows users to seamlessly switch between available languages..

212.0k](/packages/wcm-wcm-lang-switch)

PHPackages © 2026

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