sparv-sbx-whisper-import

This Sparv plugin makes it possible to use audio files as input to Sparv. The audio is transcribed to text using transformers and the KB Whisper models.

Prerequisites

• Python 3.11 or higher
• Sparv
• ffmpeg installed and available in your PATH

Install

Install in a virtual environment:

pip install sparv-sbx-whisper-import

or if you have installed sparv with pipx:

pipx inject sparv sparv-sbx-whisper-import

or if you have installed sparv with uv-pipx:

uvpipx install sparv-sbx-whisper-import --inject sparv

Usage

To use audio files as input to Sparv, first create a corpus and a Sparv configuration file. For more information about creating a corpus, see the Sparv documentation. Possible configuration options are described below.

Once your corpus and configuration file are set up, run Sparv as usual:

sparv run

Supported audio formats

[!NOTE] Only one file type and one importer can be used within a corpus. If you want to process multiple file types, please create separate corpora.

The following audio formats are supported:

Do you miss some audio format? Please check the tracking issue or open a new issue to request support for additional formats.

Command-line interface

You can use this plugin from the command-line as

# Activate virtual environment
> sbx-whisper-import --help
usage: sbx-whisper-import [-h] [--model-size MODEL_SIZE] [--verbosity VERBOSITY] INPUT

Transcribe audio file with KB-Whisper. Output is in JSON.

positional arguments:
  INPUT                 audio input to trancribe in one of the formats MP3, OGG or WAV

options:
  -h, --help            show this help message and exit
  --model-size MODEL_SIZE
                        set the size of the model
  --verbosity VERBOSITY
                        set the verbosity of the model

Configuration

To use this plugin, specify the appropriate importer for your audio files in the Sparv configuration file (config.yaml).

The default model size is small and the default verbosity is standard. You can change these settings as described below.

import:
  text_annotation: text
  # needed to use sbx_whisper_import, use one of the lines below
  importer: sbx_whisper_import:parse_mp3
  # importer: sbx_whisper_import:parse_ogg
  # importer: sbx_whisper_import:parse_wav

sbx_whisper_import:
  # One of "tiny", "base", "small", "medium" or "large"
  model_size: small
  # One of "subtitle", "standard" or "strict" (low verbosity to high verbosity)
  # NOTE: model size "medium" does support the verbosity "subtitle"
  model_verbosity: standard
  # A value between 0.0 and 1.0, defaults to 0.0.
  temperature: 0.0

export:
  annotations:
    - text
    - <token>

Annotations

The following annotations are created by the plugin:

• text with the attribute source_filename, which indicates the name of the audio file from which the text was transcribed.
• utterance with the attributes start and end, which indicate the timestamps (in seconds) of the utterance within the audio file.

Sample output:

<?xml version='1.0' encoding='utf-8'?>
<text source_filename="example.mp3">
  <utterance end="6.0" start="0.0">
    <token>Världsförklaring</token>
    <token>.</token>
  </utterance>
</text>

Metadata

The following table lists the exact models and revisions used for each combination of model size and model verbosity.

Changelog

This project keeps a changelog.

Minimum supported Python version

This library tries to support as many Python versions as possible. When a Python version is added or dropped, this library's minor version is bumped.

• v0.1.0: Python 3.11

Development

Development prerequisites

• uv
• pre-commit

For starting to develop on this repository:

• Clone the repo git clone https://github.com/spraakbanken/sparv-sbx-whisper-import.git
• Setup environment: make dev
• Install pre-commit hooks: pre-commit install

Do your work.

Tasks to do:

• Test the code with make test or make test-w-coverage.
• Test the examples with make test-examples.
• Lint the code with make lint.
• Check formatting with make check-fmt.
• Format the code with make fmt.
• Type-check the code with make type-check.

This repo uses conventional commits.

Release a new version

• Prepare the CHANGELOG: make prepare-release and then edit CHANGELOG.md.
• Add to git: git add CHANGELOG.md
• Commit with git commit -m 'chore(release): prepare release' or cog commit chore 'prepare release' release.
• Bump version (depends on `bump-my-version)
  • Major: make bumpversion part=major
  • Minor: make bumpversion part=minor
  • Patch: make bumpversion part=patch or make bumpversion
• Push main and tags to GitHub: git push main --tags or make publish
  • GitHub Actions will build, test and publish the package to PyPi.
• Add metadata for Språkbanken's resource
  • Generate metadata: make generate-metadata
  • Upload the files from examples/metadata/export/sbx_metadata/utility to https://github.com/spraakbanken/metadata/tree/main/yaml/utility.

License

This repository is licensed under the MIT license.