feat!: complete first version 0.1.0

Author: atomiechen

.gitattributes

@@ -0,0 +1,9 @@
+# Exclude files from the generated tarball
+
+# .gitignore and similar
+.git*           export-ignore
+# CI configurations
+.github         export-ignore
+
+# vscode settings
+.vscode         export-ignore

.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish Python 🐍 distributions 📦
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish_testpypi:
+        type: boolean
+        default: false
+        description: Publish to TestPyPI
+      publish_pypi:
+        type: boolean
+        default: false
+        description: Publish to PyPI
+      publish_gh_release:
+        type: boolean
+        default: true
+        description: Publish to GitHub Release
+      use_changelog:
+        type: boolean
+        default: true
+        description: Extract release notes from CHANGELOG.md
+      changelog_file:
+        type: string
+        default: CHANGELOG.md
+        description: Path to changelog file
+        required: false
+      release_tag:
+        type: string
+        description: Tag to package (empty for latest tag)
+        required: false
+
+jobs:
+  get-tag:
+    runs-on: ubuntu-latest
+    outputs:
+      release_tag: ${{ steps.set_release_tag.outputs.tag }}
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - name: Fetch all tags
+      run: |
+        git fetch --prune --unshallow --tags
+    - name: Verify and set release tag
+      id: set_release_tag
+      run: |
+        release_tag=${{ inputs.release_tag }}
+        if [ -z "$release_tag" ]; then
+          echo "Input tag is empty. Fetching latest tag."
+          release_tag=$(git describe --tags $(git rev-list --tags --max-count=1))
+          if [ -z "$release_tag" ]; then
+            echo "No latest tag available. Exiting workflow."
+            exit 1
+          fi
+        else
+          if ! git rev-parse -q --verify "refs/tags/$release_tag" >/dev/null; then
+            echo "Invalid tag '$release_tag'. Exiting workflow."
+            exit 1
+          fi
+        fi
+        echo "tag=$release_tag" >> $GITHUB_OUTPUT
+  build-n-publish:
+    needs: get-tag
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing and sigstore
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+    uses: atomiechen/reusable-workflows/.github/workflows/publish-python-distributions.yml@main
+    with:
+      publish_testpypi: ${{ inputs.publish_testpypi }}
+      publish_pypi: ${{ inputs.publish_pypi }}
+      publish_gh_release: ${{ inputs.publish_gh_release }}
+      use_changelog: ${{ inputs.use_changelog }}
+      changelog_file: ${{ inputs.changelog_file }}
+      release_tag: ${{ needs.get-tag.outputs.release_tag }}
+    secrets:
+      TEST_PYPI_API_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -1,3 +1,12 @@
+# media files
+*.pcm
+*.wav
+*.mp3
+*.mp4
+
+
+# == Below are commonly ignored files for Python projects == #
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Change Log
+
+All notable changes will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+
+
+## [0.1.0] - 2025-08-04
+
+### Added
+
+Initial features:
+
+- Both synchronous and asynchronous (`async`) support everywhere
+- Command Line Interface (CLI) and Python API
+- Auto decoding of messages with real timestamps (`FunASRMessageDecoded`)
+- Real-time audio recognition from a microphone (`mic_asr`)
+- File-based audio recognition (`file_asr`)

README.md

@@ -1 +1,207 @@
-# FunASR-Client
+# Python FunASR-Client
+
+[![GitHub](https://img.shields.io/badge/github-FunASR--Client-blue?logo=github)](https://github.com/atomiechen/FunASR-Client)
+[![PyPI](https://img.shields.io/pypi/v/funasr-client?logo=pypi&logoColor=white)](https://pypi.org/project/funasr-client/)
+
+
+Really easy-to-use Python client for [FunASR][1] runtime server.
+
+To deploy your own FunASR server, follow the [FunASR runtime guide][2], or use the improved startup scripts [here][3].
+
+## Features
+
+- ☯️ Both synchronous and asynchronous (`async`) support everywhere
+- 💻 Both Command Line Interface (CLI) and Python API
+- 🔤 Auto decoding of messages with real timestamps (`FunASRMessageDecoded`)
+- 🎙️ Real-time audio recognition from a microphone (`mic_asr`)
+- 🎵 File-based audio recognition (`file_asr`)
+
+
+## Installation
+
+Install directly from PyPI:
+
+```bash
+pip install funasr-client
+```
+
+If you want to use the microphone (`pyaudio`) for real-time recognition, install with:
+
+```bash
+pip install "funasr-client[mic]"
+```
+
+Install from github for the latest updates:
+
+```bash
+pip install "git+https://github.com/atomiechen/FunASR-Client.git"
+```
+
+## CLI
+
+The CLI supports either real-time microphone input or file input for ASR, and outputs the recognized results in JSON (file) or JSON Lines (mic) format.
+
+
+<details>
+<summary>View all CLI options by running <code>funasr-client -h</code>.</summary>
+
+```
+usage: funasr-client [-h] [-v] [--mode MODE] [--chunk_size P C F] [--chunk_interval CHUNK_INTERVAL] [--audio_fs AUDIO_FS]
+                     [--hotwords WORD:WEIGHT [WORD:WEIGHT ...]] [--no-itn] [--svs_lang SVS_LANG] [--no-svs_itn] [--async]
+                     URI [FILE_PATH]
+
+FunASR Client CLI v0.1.0. Use microphone for real-time recognition (needs pyaudio), or specify input audio file.
+
+positional arguments:
+  URI                   WebSocket URI to connect to the FunASR server.
+  FILE_PATH             Optional input audio file path (suppress microphone). (default: None)
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -v, --version         show program's version number and exit
+  --mode MODE           offline, online, 2pass (default: 2pass)
+  --chunk_size P C F    Chunk size: past, current, future. (default: [5, 10, 5])
+  --chunk_interval CHUNK_INTERVAL
+                        Chunk interval. (default: 10)
+  --audio_fs AUDIO_FS   Audio sampling frequency. (default: 16000)
+  --hotwords WORD:WEIGHT [WORD:WEIGHT ...]
+                        Hotwords with weights, e.g., 'hello:10 world:5'. (default: [])
+  --no-itn              Disable ITN (default: True)
+  --svs_lang SVS_LANG   SVS language. (default: auto)
+  --no-svs_itn          Disable SVS ITN (default: True)
+  --async               Use asynchronous client. (default: False)
+```
+
+</details>
+
+### Microphone Real-time ASR
+
+Requires `pyaudio` for microphone support (install it using `pip install "funasr-client[mic]"`).
+
+```sh
+funasr-client ws://localhost:10096
+```
+
+### File ASR
+
+```sh
+funasr-client ws://localhost:10096 path/to/audio.wav
+```
+
+
+## Python API
+
+Sync API (`funasr_client`):
+```python
+from funasr_client import funasr_client
+
+with funasr_client("ws://localhost:10096") as client:
+    @client.on_message
+    def callback(msg):
+        print("Received:", msg)
+```
+
+Async API (`async_funasr_client`):
+```python
+from funasr_client import async_funasr_client
+
+async def main():
+    async with async_funasr_client("ws://localhost:10096") as client:
+        # NOTE: sync callback is also supported
+        @client.on_message
+        async def callback(msg):
+            print("Received:", msg)
+```
+
+See scripts in the [examples directory](examples/) for real-world usage.
+
+### Registering Callbacks in non-blocking mode
+
+By default, the client runs in non-blocking mode, which allows you to continue using your program while waiting for ASR results. 
+It starts a background loop in a thread (sync) or an async task (async) to handle incoming messages.
+
+Two ways to register message callbacks (**both** sync and async are supported):
+1. Using `@client.on_message` decorator (like shown above).
+2. Passing `callback` handler to the constructor.
+    ```python
+    funasr_client(
+        ...
+        callback=lambda msg: print(msg)
+    )
+    ```
+
+> [!NOTE]  
+> Sync callback in async client will be run in a thread pool executor.
+
+
+### Blocking Mode
+
+To run in blocking mode (disable background loop), pass `blocking=True` to the client constructor.
+It is your responsibility to call `client.stream()` or `client.recv()` to receive messages.
+
+Use `client.stream()` (async) generator to receive messages in a loop:
+
+```python
+from funasr_client import funasr_client
+with funasr_client("ws://localhost:10096", blocking=True) as client:
+    for msg in client.stream():
+        print("Received:", msg)
+```
+
+Or, use the low-level `client.recv()` method to receive messages one by one:
+
+```python
+from funasr_client import funasr_client
+with funasr_client("ws://localhost:10096", blocking=True) as client:
+    while True:
+        msg = client.recv()
+        if msg is None:
+            break
+        print("Received:", msg)
+```
+
+
+### Decoding Messages
+
+By default, the client decodes response messages into `FunASRMessageDecoded` dicts, which parses `timestamps` JSON string into a list.
+If `start_time` (int in ms) is provided to the client, `real_timestamp` and `real_stamp_sents` will be calculated and added to the decoded message.
+
+To disable decoding, pass `decode=False` to the constructor to get original dict object.
+
+
+### Microphone Real-time ASR
+
+Open a microphone stream and get the stream of **decoded** messages (`mic_asr` / `async_mic_asr`):
+
+```python
+from funasr_client import mic_asr
+with mic_asr("ws://localhost:10096") as msg_gen:
+  for msg in msg_gen:
+      print("Received:", msg)
+```
+
+### File ASR
+
+Get the final result as a **merged decoded** message (`file_asr` / `async_file_asr`):
+
+```python
+from funasr_client import file_asr
+
+result = file_asr("path/to/audio.wav", "ws://localhost:10096")
+print(result)
+```
+
+Or, get the stream of **decoded or original** (depends on `decode` option) messages (`file_asr_stream` / `async_file_asr_stream`):
+
+```python
+from funasr_client import file_asr_stream
+
+with file_asr_stream("path/to/audio.wav", "ws://localhost:10096") as msg_gen:
+    for msg in msg_gen:
+        print("Received:", msg)
+```
+
+
+[1]: https://github.com/modelscope/FunASR
+[2]: https://github.com/modelscope/FunASR/blob/main/runtime/readme.md
+[3]: https://gist.github.com/atomiechen/2deaf80dba21b4434ab21d6bf656fbca

examples/decode.py

@@ -0,0 +1,47 @@
+import asyncio
+import os
+
+from dotenv import load_dotenv
+from funasr_client import async_funasr_client
+
+
+load_dotenv()
+FUNASR_URI = os.getenv("FUNASR_URI", "wss://www.funasr.com:10096/")
+
+
+async def with_decode():
+    async with async_funasr_client(
+        uri=FUNASR_URI,
+        blocking=True,
+        decode=True,
+    ) as client:
+        print("Connected to FunASR WebSocket server.")
+        # send some audio data to the server
+        with open("test.pcm", "rb") as f:
+            await client.send(f.read())
+        async for response in client.stream():
+            # check your IDE to see the type of response: FunASRMessageDecoded
+            print("Received decoded response:", response)
+
+
+async def no_decode():
+    async with async_funasr_client(
+        uri=FUNASR_URI,
+        blocking=True,
+        decode=False,
+    ) as client:
+        print("Connected to FunASR WebSocket server.")
+        # send some audio data to the server
+        with open("test.pcm", "rb") as f:
+            await client.send(f.read())
+        async for response in client.stream():
+            # check your IDE to see the type of response: FunASRMessage
+            print("Received original response:", response)
+
+
+if __name__ == "__main__":
+    decode = True
+    if decode:
+        asyncio.run(with_decode())
+    else:
+        asyncio.run(no_decode())