{"id":13825646,"url":"https://github.com/speechmatics/speechmatics-python","last_synced_at":"2025-12-24T17:47:35.656Z","repository":{"id":40390362,"uuid":"224633111","full_name":"speechmatics/speechmatics-python","owner":"speechmatics","description":"Python library and CLI for Speechmatics","archived":false,"fork":false,"pushed_at":"2024-10-17T09:14:05.000Z","size":3089,"stargazers_count":57,"open_issues_count":7,"forks_count":14,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-18T15:31:19.462Z","etag":null,"topics":["cli","speech-recognition","speech-to-text","transcription"],"latest_commit_sha":null,"homepage":"https://speechmatics.github.io/speechmatics-python/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/speechmatics.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-28T10:56:50.000Z","updated_at":"2024-10-04T12:05:35.000Z","dependencies_parsed_at":"2022-07-12T18:01:45.618Z","dependency_job_id":"fd133f32-89a8-4f52-91de-f0eca5101e36","html_url":"https://github.com/speechmatics/speechmatics-python","commit_stats":{"total_commits":204,"total_committers":29,"mean_commits":"7.0344827586206895","dds":0.7941176470588236,"last_synced_commit":"239b968b22082bf9957df76afaa90d5491e35704"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speechmatics%2Fspeechmatics-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speechmatics%2Fspeechmatics-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speechmatics%2Fspeechmatics-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speechmatics%2Fspeechmatics-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/speechmatics","download_url":"https://codeload.github.com/speechmatics/speechmatics-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224273044,"owners_count":17284307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","speech-recognition","speech-to-text","transcription"],"created_at":"2024-08-04T09:01:24.711Z","updated_at":"2025-12-24T17:47:35.650Z","avatar_url":"https://github.com/speechmatics.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Legacy Speechmatics Python Client\n\n\u003e **⚠️ WARNING: This package (`speechmatics-python`) has been deprecated.**\n\u003e\n\u003e - **No new features** will be added\n\u003e - **Bug fixes and security patches only** until **2025-12-31**\n\u003e\n\n### Migration Path\n\n**New Official SDKs** (at [speechmatics-python-sdk](https://github.com/speechmatics/speechmatics-python-sdk)):\n\n| Old Package | New Package | Purpose | Migration Guide |\n|-------------|-------------|---------|-----------------|\n| `speechmatics-python` | [`speechmatics-batch`](https://pypi.org/project/speechmatics-batch) | Batch transcription | [📖 Batch Migration Guide](https://github.com/speechmatics/speechmatics-python-sdk/blob/main/sdk/batch/MIGRATION.md) |\n| `speechmatics-python` | [`speechmatics-rt`](https://pypi.org/project/speechmatics-rt) | Real-time transcription | [📖 RT Migration Guide](https://github.com/speechmatics/speechmatics-python-sdk/blob/main/sdk/rt/MIGRATION.md) |\n| `speechmatics.cli` | Not available (will be released as a separate package) | | |\n\nPython client library and CLI for Speechmatics Realtime and Batch ASR v2 APIs.\n\n## Getting started\n\nTo install from PyPI:\n```bash\npip install speechmatics-python\n```\n\nTo use the sm-metrics tool for diarization features and speaker identification metrics, install with the optional dependencies:\n```bash\npip install speechmatics-python[metrics]\n```\nTo install from source:\n```bash\ngit clone https://github.com/speechmatics/speechmatics-python\ncd speechmatics-python \u0026\u0026 python setup.py install\n```\nWindows users may need to run the install command with an extra flag:\n```bash\npython setup.py install --user\n```\n\n## Docs\n\nThe speechmatics python SDK and CLI is documented at https://speechmatics.github.io/speechmatics-python/.\n\nThe Speechmatics API and product documentation can be found at https://docs.speechmatics.com.\n\n## Real-Time Client Usage\n```python\nfrom speechmatics.models import *\nimport speechmatics\n\n# Change to your own file\nPATH_TO_FILE = \"tests/data/ch.wav\"\nLANGUAGE = \"en\"\n\n# Generate an API key at https://portal.speechmatics.com/manage-access/\nAPI_KEY = \"\"\n\n# Create a transcription client from config defaults\nsm_client = speechmatics.client.WebsocketClient(API_KEY)\n\nsm_client.add_event_handler(\n    event_name=ServerMessageType.AddPartialTranscript,\n    event_handler=print,\n)\n\nsm_client.add_event_handler(\n    event_name=ServerMessageType.AddTranscript,\n    event_handler=print,\n)\n\nconf = TranscriptionConfig(\n    language=LANGUAGE, enable_partials=True, max_delay=5, enable_entities=True,\n)\n\nprint(\"Starting transcription (type Ctrl-C to stop):\")\nwith open(PATH_TO_FILE, \"rb\") as fd:\n    try:\n        sm_client.run_synchronously(fd, conf)\n    except KeyboardInterrupt:\n        print(\"\\nTranscription stopped.\")\n\n```\n\n## Batch Client Usage\n```python\nfrom speechmatics.models import ConnectionSettings, BatchTranscriptionConfig\nfrom speechmatics.batch_client import BatchClient\nfrom httpx import HTTPStatusError\n\nAPI_KEY = \"YOUR_API_KEY\"\nPATH_TO_FILE = \"example.wav\"\nLANGUAGE = \"en\"\n\n# Open the client using a context manager\nwith BatchClient(API_KEY) as client:\n    try:\n        job_id = client.submit_job(PATH_TO_FILE, BatchTranscriptionConfig(LANGUAGE))\n        print(f'job {job_id} submitted successfully, waiting for transcript')\n\n        # Note that in production, you should set up notifications instead of polling.\n        # Notifications are described here: https://docs.speechmatics.com/features-other/notifications\n        transcript = client.wait_for_completion(job_id, transcription_format='txt')\n        # To see the full output, try setting transcription_format='json-v2'.\n        print(transcript)\n    except HTTPStatusError as e:\n        if e.response.status_code == 401:\n            print('Invalid API key - Check your API_KEY at the top of the code!')\n        elif e.response.status_code == 400:\n            print(e.response.json()['detail'])\n        else:\n            raise e\n```\n\n## Example command-line usage\n\nA complete list of commands and flags can be found in the SDK docs at https://speechmatics.github.io/speechmatics-python/.\n\n  ### Configuring Auth Tokens\n- Setting an auth token for CLI authentication:\n   ```bash\n   speechmatics config set --auth-token $AUTH_TOKEN\n   ```\n  Auth tokens are stored in toml config at HOME_DIR/.speechmatics/config.\n  You may also set the auth_token for each CLI command using the --auth-token flag.\n  The --auth-token flag overrides the value stored in the config file, e.g.\n   ```bash\n   speechmatics transcribe --auth-token $AUTH_TOKEN example_audio.wav\n   ```\n\n- Removing an auth_token from the toml file:\n   ```bash\n   speechmatics config unset --auth-token\n   ```\n\n- Setting URLs for connecting to transcribers. These values can be used in places of the --url flag:\n   ```bash\n   speechmatics config set --rt-url wss://eu2.rt.speechmatics.com/v2 --batch-url https://asr.api.speechmatics.com/v2\n   ```\n\n- Unsetting transcriber URLs in the toml config:\n   ```bash\n   speechmatics config unset --rt-url --batch-url\n   ```\n\n- Setting URLs for connecting to transcribers. These values can be used in places of the --url flag:\n   ```bash\n   speechmatics config set --rt-url wss://eu2.rt.speechmatics.com/v2 --batch-url https://asr.api.speechmatics.com/v2\n   ```\n\n- Unsetting transcriber URLs in the toml config:\n   ```bash\n   speechmatics config unset --rt-url --batch-url\n   ```\n\n  ### Realtime ASR\n- Starting a real-time session for self-service SaaS customers using a .wav file as the input audio:\n\n   ```bash\n   speechmatics transcribe --lang en example_audio.wav\n   ```\n\n- Real-time transcription of online stream (needs ffmpeg installed):\n  ```bash\n  ffmpeg -v 0 -i https://cdn.bitmovin.com/content/assets/art-of-motion-dash-hls-progressive/mpds/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.mpd \\\n  -f s16le -ar 44100 -ac 1 -acodec pcm_s16le - | \\\n  speechmatics transcribe --raw pcm_s16le --sample-rate 44100 -\n\n- Starting a real-time session for enterprise SaaS customers using a .wav file as the input audio:\n\n   ```bash\n   # Point URL to the a SaaS enterprise runtime\n   URL=wss://neu.rt.speechmatics.com/v2/en\n\n   speechmatics transcribe --url $URL example_audio.wav\n   ```\n\n- Starting a real-time session for on-prem customers using a .wav file as the input audio:\n\n   ```bash\n   # Point URL to the local instance of the realtime appliance\n   URL=ws://realtimeappliance.yourcompany:9000/v2\n\n   speechmatics transcribe --url $URL --lang en --ssl-mode none example_audio.wav\n   ```\n\n- Show the messages that are going over the websocket connection using verbose output:\n\n   ```bash\n   speechmatics -v transcribe --url $URL --ssl-mode none example_audio.wav\n   ```\n\n- The CLI also accepts an audio stream on standard input.\n  Transcribe the piped input audio:\n\n   ```bash\n   cat example_audio.wav | speechmatics transcribe --url $URL --ssl-mode none -\n   ```\n\n- Pipe audio directly from the microphone (example uses MacOS with [ffmpeg](https://ffmpeg.org/ffmpeg-devices.html#avfoundation))\n\n  List available input devices:\n\n  ```bash\n  ffmpeg -f avfoundation -list_devices true -i \"\"\n  ```\n\n  There needs to be at least one available microphone attached to your computer.\n  The command below gets the microphone input and pipes it to the transcriber.\n  You may need to change the sample rate to match the sample rate that your machine records at.\n  You may also need to replace `:default` with something like `:0` or `:1` if you want to use a specific microphone.\n\n  ```bash\n  ffmpeg -loglevel quiet -f avfoundation -i \":default\" -f f32le -acodec pcm_f32le -ar 44100 - \\\n  \u003e   | speechmatics transcribe --url $URL --ssl-mode none --raw pcm_f32le --sample-rate 44100 -\n  ```\n\n- Transcribe in real-time with partials (example uses Ubuntu with ALSA).\n  In this mode, the transcription engine produces words instantly, which may get updated as additional context becomes available.\n\n  List available input devices:\n\n  ```bash\n  cat /proc/asound/cards\n  ```\n\n  Record microphone audio and pipe to transcriber:\n\n  ```bash\n  ffmpeg -loglevel quiet -f alsa -i hw:0 -f f32le -acodec pcm_f32le -ar 44100 - \\\n      | speechmatics transcribe --url $URL --ssl-mode none --enable-partials --raw pcm_f32le --sample-rate 44100 -\n  ```\n\n  Add the `--print-json` argument to see the raw JSON transcript messages being sent rather than just the plaintext transcript.\n\n  ### Batch ASR\n- Submit a .wav file for batch ASR processing\n\n   ```bash\n   speechmatics batch transcribe --lang en example_audio.wav\n   ```\n\n- Files may be submitted for asynchronous processing\n\n    ```bash\n   speechmatics batch submit example_audio.wav\n    ```\n\n- Enterprise SaaS and on-prem customers can point to a custom runtime:\n\n   ```bash\n   # Point URL to a custom runtime (in this case, the trial runtime)\n   URL=https://trial.asr.api.speechmatics.com/v2/\n\n   speechmatics batch transcribe --url $URL example_audio.wav\n   ```\n\n- Check processing status of a job\n\n    ```bash\n   # $JOB_ID is from the submit command output\n   speechmatics batch job-status --job-id $JOB_ID\n    ```\n\n- Retrieve completed transcription\n\n    ```bash\n   # $JOB_ID is from the submit command output\n   speechmatics batch get-results --job-id $JOB_ID\n    ```\n\n- Submit a job with automatic language identification\n\n    ```bash\n   speechmatics batch transcribe --language auto --langid-langs en,es example_audio.wav\n    ```\n    If Speechmatics is not able to identify a language with high enough confidence,  the job will be rejected. This is to reduce the risk of transcribing incorrectly.\n\n    `--langid-langs` is optional and specifies what language(s) you expect to be detected in the source files.\n\n\n- Submit a job with translation\n\n    ```bash\n  speechmatics batch transcribe --translation-langs de,es --output-format json-v2 example_audio.wav\n    ```\n  `--translation-langs` is supported in asynchronous mode as well, and translation output can be retrieved using `get-results` with `--output-format json-v2` set.\n\n  When combining language identification with translation, we can't know if the identified language can be translated\n  to your translation targets. If the translation pair is not supported, the error will be recorded in the metadata of the transcript.\n\n- Start a real-time transcription with translation session using microphone audio and pipe to transcriber\n\n  ```bash\n  ffmpeg -loglevel quiet -f alsa -i hw:0 -f f32le -acodec pcm_f32le -ar 44100 - \\\n      | speechmatics rt transcribe --url $URL --ssl-mode none --raw pcm_f32le --sample-rate 44100 \\\n  --print-json --translation-langs fr -\n  ```\n\n- Submit a job with summarization\n\n  ```bash\n  speechmatics batch transcribe --summarize --output-format json-v2 example_audio.wav\n    ```\n\n- Submit a job with sentiment analysis\n\n  ```bash\n  speechmatics batch transcribe --sentiment-analysis --output-format json-v2 example_audio.wav\n    ```\n\n- Submit a job with topic detection\n\n  ```bash\n  speechmatics batch transcribe --detect-topics --output-format json-v2 example_audio.wav\n    ```\n\n- Submit a job with auto chapters\n\n  ```bash\n  speechmatics batch transcribe --detect-chapters --output-format json-v2 example_audio.wav\n    ```\n\n  ### Custom Transcription Config File\n- Instead of passing all the transcription options via the command line you can also pass a transcription config file.\n  The config file is a JSON file that contains the transcription options.\n  The config file can be passed to the CLI using the `--config-file` option.\n\n    ```bash\n  speechmatics transcribe --config-file transcription_config.json example_audio.wav\n    ```\n- The format of this JSON file is described in detail in the\n  [Batch API documentation](https://docs.speechmatics.com/jobsapi#tag/TranscriptionConfig)\n  and [RT API documentation](https://docs.speechmatics.com/rt-api-ref#transcription-config).\n\n\n## SM Metrics\n\nThis package includes tooling for benchmarking transcription and diarization accuracy.\n\nFor more information, see the `asr_metrics/README.md`\n\n## Testing\n\nTo install development dependencies and run tests\n\n    pip install -r requirements-dev.txt\n    make test\n\n\n## Support\n\nIf you have any issues with this library or encounter any bugs then please get in touch with us at support@speechmatics.com.\n\n---\n\nLicense: [MIT](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeechmatics%2Fspeechmatics-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspeechmatics%2Fspeechmatics-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeechmatics%2Fspeechmatics-python/lists"}