qwenlm/qwen3-asr-toolkit

1. This repository is a small multi-language toolkit centered on one pipeline: take long audio/video, split it into transcribable chunks, send those chunks to the Qwen-ASR service, then stitch the results back together. The Python package is the primary product; the Java directory is a standalone reference implementation of the same idea.

2. The Python code is organized into three main subsystems:

- qwen3asr.py: the CLI/orchestration layer

- audio_tools.py: media loading, conversion, chunking, and subtitle-related helpers

- call_api.py: the DashScope/Qwen-ASR request boundary

This separation maps cleanly to the architecture: input preparation, remote inference, and result handling.

3. The main data flow starts with an input media source that can be either a local file or a remote URL. The tool normalizes that source into audio suitable for the API, then uses voice activity detection to find natural breakpoints instead of cutting blindly by time.

4. Media preprocessing is a key boundary in this repo. The README indicates FFmpeg is used to accept many input formats and resample them into the 16 kHz mono format expected by the ASR API. Temporary chunk files are stored under a configurable cache directory, which makes the preprocessing stage explicit and separable from the transcription stage.

5. Chunking is controlled by VAD and a target segment duration. The design goal is to keep chunks under the API’s 3-minute limit while avoiding mid-sentence cuts. This means the splitter is not just a file splitter; it is a semantic boundary detector that tries to preserve speech continuity.

6. API interaction is isolated behind the call_api.py layer. That layer is the external-service boundary to Alibaba Cloud DashScope, authenticated via DASHSCOPE_API_KEY or a CLI argument. The repository does not embed a model locally in Python; it depends on the hosted Qwen-ASR service for transcription.

7. Long-form throughput is improved by parallelism. The toolkit submits chunk requests concurrently using multiple threads, then reorders and aggregates the returned text segments. In architectural terms, transcription is a fan-out/fan-in stage: split into chunks, dispatch in parallel, collect in order.

8. After transcription, the tool performs cleanup/post-processing on the assembled text. The README calls out removal of hallucinations and repetitive artifacts, so the final output stage is not a raw API passthrough; it is a normalization step that improves readability before writing the transcript.

9. Output generation is file-oriented. The final transcript is printed to the terminal and saved as a .txt file next to the source media. If enabled, an .srt subtitle file is generated from the same segmented timing information, so subtitle creation is a secondary output derived from the VAD/chunk timeline.

10. The package boundary is straightforward: install via pip, then invoke the qwen3-asr command. Python 3.8+, FFmpeg, and the DashScope API key are the main runtime dependencies that materially affect architecture.

11. The Java example in examples/java-example mirrors the same pipeline in another runtime. App.java appears to be the entry point, AudioSplitter.java handles chunking, SlieroVadDetector.java and SlieroVadOnnxModel.java wrap VAD inference, and utils/Result.java / utils/Util.java support orchestration. This example includes an embedded silero_vad.onnx, so unlike the Python path it demonstrates local ONNX-based VAD integration.

12. From an architecture-diagram perspective, the important boundaries are: media input, audio normalization/VAD splitting, parallel remote ASR calls, post-processing/ordering, and output files. The Python package is the production flow; the Java example is a parallel reference implementation of the same control flow.