Update README and chat template for custom hotwords

README.md

@@ -68,10 +68,10 @@ The Qwen3-ASR family includes **Qwen3-ASR-1.7B** and **Qwen3-ASR-0.6B**, which s
 
 ## Usage
 
-Qwen3-ASR is supported natively in 🤗 Transformers. Until it is part of an official Transformers release, install from source:
+Qwen3-ASR is supported natively in 🤗 Transformers, starting from v5.13.0.
 
 ```bash
-pip install git+https://github.com/huggingface/transformers
+pip install "transformers>=5.13.0"
 ```
 
 ### Simple transcription
@@ -112,9 +112,9 @@ Transcription: Mr. Quilter is the apostle of the middle classes, and we are glad
 """
 ```
 
-### Language hint
+### Forcing the language
 
-Pass a language hint to skip auto-detection.
+You can force the transcription language as shown below.
 
 ```python
 from transformers import AutoProcessor, AutoModelForMultimodalLM
@@ -131,14 +131,36 @@ output_ids = model.generate(**inputs, max_new_tokens=256)
 generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
 print(f"Auto-detect: {processor.decode(generated_ids, return_format='transcription_only')[0]}")
 
-# With language hint (language code or full name both accepted)
+# With forced language
 inputs = processor.apply_transcription_request(
     audio="https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_zh.wav",
-    language="Chinese",  # or "zh"
+    language="Chinese",  # or language code "zh"
 ).to(model.device, model.dtype)
 output_ids = model.generate(**inputs, max_new_tokens=256)
 generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
-print(f"With hint:   {processor.decode(generated_ids, return_format='transcription_only')[0]}")
+print(f"Forced:      {processor.decode(generated_ids, return_format='transcription_only')[0]}")
+```
+
+### Context / hotwords
+
+You can pass free-form context (e.g. domain-specific vocabulary, names, or background information) via `prompt` to bias the transcription.
+
+```python
+from transformers import AutoProcessor, AutoModelForMultimodalLM
+
+model_id = "Qwen/Qwen3-ASR-1.7B-hf"
+processor = AutoProcessor.from_pretrained(model_id)
+model = AutoModelForMultimodalLM.from_pretrained(model_id, device_map="auto")
+
+inputs = processor.apply_transcription_request(
+    audio="https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav",
+    prompt="Vocabulary: Quilter, apostle, gospel.",
+    language="English",
+).to(model.device, model.dtype)
+
+output_ids = model.generate(**inputs, max_new_tokens=256)
+generated_ids = output_ids[:, inputs["input_ids"].shape[1]:]
+print(processor.decode(generated_ids, return_format="transcription_only")[0])
 ```
 
 ### Batch inference
@@ -171,7 +193,9 @@ for i, text in enumerate(transcriptions):
 
 ### Chat template
 
-`apply_transcription_request` is a convenience wrapper around `apply_chat_template`. Use the chat template directly for more control, such as providing a language hint via a system message.
+Qwen3 ASR also accepts chat template inputs. The `apply_transcription_request` usage [above](#simple-transcription) is a convenience wrapper for `apply_chat_template`.
+
+The language can be forced through the chat template by *prefilling* the assistant turn with `language <NAME><asr_text>` and passing `continue_final_message=True`, which is what `apply_transcription_request` does under the hood. Note that if forcing the language, a prefill should be set for all audio in a batch (as shown below).
 
 ```python
 from transformers import AutoProcessor, Qwen3ASRForConditionalGeneration
@@ -182,7 +206,8 @@ model = Qwen3ASRForConditionalGeneration.from_pretrained(model_id, device_map="a
 
 chat_template = [
     [
-        {"role": "system", "content": [{"type": "text", "text": "English"}]},
+        # Context/hotwords as system message
+        {"role": "system", "content": [{"type": "text", "text": "Vocabulary: Quilter, apostle, gospel."}]},
         {
             "role": "user",
             "content": [
@@ -192,6 +217,8 @@ chat_template = [
                 },
             ],
         },
+        # empty prefill since forcing language in the other sample
+        {"role": "assistant", "content": [{"type": "text", "text": ""}]},
     ],
     [
         {
@@ -203,11 +230,12 @@ chat_template = [
                 },
             ],
         },
+        {"role": "assistant", "content": [{"type": "text", "text": "language Chinese<asr_text>"}]},
     ],
 ]
 
 inputs = processor.apply_chat_template(
-    chat_template, tokenize=True, return_dict=True,
+    chat_template, tokenize=True, return_dict=True, continue_final_message=True,
 ).to(model.device, model.dtype)
 
 output_ids = model.generate(**inputs, max_new_tokens=256)
@@ -217,7 +245,9 @@ for text in transcriptions:
     print(text)
 ```
 
-### Training / Fine-tuning
+### Training / fine-tuning
+
+Qwen3 ASR can be trained with the loss outputted by the model. Put the target transcript in the assistant turn — in the model's output format `language <NAME><asr_text>...` to preserve the pretrained behavior — and pass `output_labels=True`. Audio and padding positions are masked automatically.
 
 ```python
 from transformers import AutoProcessor, Qwen3ASRForConditionalGeneration
@@ -227,26 +257,24 @@ processor = AutoProcessor.from_pretrained(model_id)
 model = Qwen3ASRForConditionalGeneration.from_pretrained(model_id, device_map="auto")
 model.train()
 
-chat_template = [
+transcript = "Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel."
+conversation = [
     [
         {
             "role": "user",
             "content": [
-                {
-                    "type": "text",
-                    "text": "Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel.",
-                },
                 {
                     "type": "audio",
                     "path": "https://huggingface.co/datasets/bezzam/audio_samples/resolve/main/librispeech_mr_quilter.wav",
                 },
             ],
-        }
+        },
+        {"role": "assistant", "content": [{"type": "text", "text": f"language English<asr_text>{transcript}"}]},
     ],
 ]
 
 inputs = processor.apply_chat_template(
-    chat_template, tokenize=True, return_dict=True, output_labels=True,
+    conversation, tokenize=True, return_dict=True, processor_kwargs={"output_labels": True},
 ).to(model.device, model.dtype)
 
 loss = model(**inputs).loss

chat_template.jinja

@@ -1,31 +1,8 @@
-{%- set ns = namespace(system_text="") -%}
-{%- for m in messages -%}
-  {%- if m.role == 'system' -%}
-    {%- if m.content is string -%}
-      {%- set ns.system_text = ns.system_text + m.content -%}
-    {%- else -%}
-      {%- for c in m.content -%}
-        {%- if c.type == 'text' and (c.text is defined) -%}
-          {%- set ns.system_text = ns.system_text + c.text -%}
-        {%- endif -%}
-      {%- endfor -%}
-    {%- endif -%}
-  {%- endif -%}
-{%- endfor -%}
-
-{%- set ns2 = namespace(audio_tokens="") -%}
-{%- for m in messages -%}
-  {%- if m.content is not string -%}
-    {%- for c in m.content -%}
-      {%- if c.type == 'audio' or ('audio' in c) or ('audio_url' in c) -%}
-        {%- set ns2.audio_tokens = ns2.audio_tokens + "<|audio_start|><|audio_pad|><|audio_end|>" -%}
-      {%- endif -%}
-    {%- endfor -%}
-  {%- endif -%}
-{%- endfor -%}
-
-{{- '<|im_start|>system\n' + (ns.system_text if ns.system_text is string else '') + '<|im_end|>\n' -}}
-{{- '<|im_start|>user\n' + ns2.audio_tokens + '<|im_end|>\n' -}}
-{%- if add_generation_prompt -%}
-{{- '<|im_start|>assistant\n' -}}
-{%- endif -%}
+{%- set ns = namespace(system_text='') -%}{%- for m in messages -%}{%- if m.role == 'system' -%}{%- if m.content is string -%}{%- set ns.system_text = ns.system_text + m.content -%}{%- else -%}{%- for c in m.content -%}{%- if c.type == 'text' and (c.text is defined) -%}{%- set ns.system_text = ns.system_text + c.text -%}{%- endif -%}{%- endfor -%}{%- endif -%}{%- endif -%}{%- endfor -%}{%- set ns2 = namespace(audio_tokens='') -%}{%- for m in messages -%}{%- if m.content is not string -%}{%- for c in m.content -%}{%- if c.type == 'audio' or ('audio' in c) or ('audio_url' in c) -%}{%- set ns2.audio_tokens = ns2.audio_tokens + '<|audio_start|><|audio_pad|><|audio_end|>' -%}{%- endif -%}{%- endfor -%}{%- endif -%}{%- endfor -%}{{- '<|im_start|>system
+' + ns.system_text + '<|im_end|>
+' -}}{{- '<|im_start|>user
+' + ns2.audio_tokens + '<|im_end|>
+' -}}{%- for m in messages -%}{%- if m.role == 'assistant' -%}{%- set ns3 = namespace(assistant_text='') -%}{%- if m.content is string -%}{%- set ns3.assistant_text = m.content -%}{%- else -%}{%- for c in m.content -%}{%- if c.type == 'text' and (c.text is defined) -%}{%- set ns3.assistant_text = ns3.assistant_text + c.text -%}{%- endif -%}{%- endfor -%}{%- endif -%}{{- '<|im_start|>assistant
+' -}}{% generation %}{{- ns3.assistant_text + '<|im_end|>
+' -}}{% endgeneration %}{%- endif -%}{%- endfor -%}{%- if add_generation_prompt -%}{{- '<|im_start|>assistant
+' -}}{%- endif -%}