Converting text that contains complex mathematical formulas into fluent and accurate speech is a challenge in scenarios such as audiobooks and online education. CosyVoice parses formulas embedded in text and reads them aloud in a natural way. This feature significantly improves the listening experience for content in subjects such as mathematics and physics.
This feature only supports speech synthesis in the Chinese language. Formulas may not be pronounced correctly in other languages. All pronunciation examples in this topic are translations and do not represent the actual performance.
Procedure
Wrap the formulas in your text with specific separators, and then call the speech synthesis API.
Mark formulas with separators
Wrap the formulas with one of the following separators. This allows the engine to detect and parse them.
The choice of separator does not affect the synthesis result. You can use any of the following formats.
$...$$$...$$\(...\)\[...\]
Example:
Here is the quadratic formula: $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$. Calculate carefully.Call the API to request speech synthesis
Call the speech synthesis API with the text that contains the marked formulas. Note that in a JSON-formatted request body or a string literal, the backslash (
\) is an escape character. Therefore, you must write it as\\.Example call (in Python):
# coding=utf-8 import dashscope from dashscope.audio.tts_v2 import * # If the API key is not configured as an environment variable, replace 'your-api-key' with your actual API key. # dashscope.api_key = "your-api-key" # Model model = "cosyvoice-v3-flash" # Voice # Different model versions require correspounding voices: # cosyvoice-v3-flash/cosyvoice-v3-plus: Voices such as longanyang # cosyvoice-v2: Voices such as longxiaochun_v2 voice = "longanyang" # Instantiate SpeechSynthesizer and pass request parameters, such as the model and voice, to the constructor. synthesizer = SpeechSynthesizer(model=model, voice=voice) # Send the text for synthesis to get the binary audio data. audio = synthesizer.call("Here is the quadratic formula: $x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$. Calculate carefully.") # When you send text for the first time, a WebSocket connection is established. # Therefore, the first-packet latency includes the time it takes to establish the connection. print('[Metric] Request ID: {}, First-packet latency: {} ms'.format( synthesizer.get_last_request_id(), synthesizer.get_first_package_delay())) # Save the audio to a local file. with open('output.mp3', 'wb') as f: f.write(audio)
Supported tags and symbols
The following tables list the currently supported tags and symbols.
Basic mathematics
Tag or symbol | Function | Formula content example | Formula input example | Pronunciation |
+ | Add | 2 + 3 = 5 | $2 + 3 = 5$ | Two plus three equals five |
- | Subtract | 3 - 2 = 1 | $3 - 2 = 1$ | Three minus two equals one |
\pm | Plus or minus | \pm 1 \pm 2 | $\pm 1\pm 2$ | Plus or minus one, plus or minus two |
Positive or negative | ||||
\times | Multiply | 2 \times 3 = 6 | $2 \times 3 = 6$ | Two times three equals six |
× | 2 × 3 = 6 | $$2 × 3 = 6$$ | ||
* | 2 * 3 = 6 | \(2 * 3 = 6\) | ||
\div | Divide | 6\div2=3 | \[6\div2=3\] | Six divided by two equals three |
÷ | 6÷2=3 | $6÷2=3$ | ||
/ | 6/2=3 | $6/2=3$ | ||
= | Equals | 3+5=8 | $3+5=8$ | Three plus five equals eight |
< | Less than | 1< 2 | $1< 2$ | One is less than two |
≤ | Less than or equal to | 3≤5 | $3≤5$ | Three is less than or equal to five |
<= | 3<=5 | $3<=5$ | ||
\leq | 3\leq5 | $3\leq 5$ | ||
\le | 3\le5 | $3\le 5$ | ||
\leqq | 3\leqq5 | $3\leqq 5$ | ||
\leqslant | 3\leqslant5 | $3\leqslant 5$ | ||
> | Greater than | 2>1 | $2>1$ | Two is greater than one |
≥ | Greater than or equal to | 5≥3 | $5≥3$ | Five is greater than or equal to three |
>= | 5>=3 | $5>=3$ | ||
\geq | 5\geq3 | $5\geq 3$ | ||
\ge | 5\ge3 | $5\ge 3$ | ||
\geqq | 5\geqq3 | $5\geqq 3$ | ||
\geqslant | 5\geqslant3 | $5\geqslant 3$ | ||
\frac | Score | 2\frac3 | $\frac {2}{3}$ | Two-thirds |
^ | Power | 2^1 | $2^{1}$ | Two to the first power |
\sqrt | Root | \sqrt{9} = 3 | $\sqrt {9} = 3$ | The square root of nine equals three |
\sqrt[3]{8} = 2 | $\sqrt[3]{8} = 2$ | The cube root of eight equals two | ||
\% | Percentage | 5\% | $5\%$ | Five percent |
| | Absolute value | ∣3∣=3 | $|3| =3$ | The absolute value of three equals three |
\vert | 3\vert=3 | $\vert 3\vert =3$ | The absolute value of three equals three | |
\lg | Logarithm | lg {10} | $\lg {10}$ | log ten |
\log | Logarithm | \log{5} | $\log{5}$ | log five |
\ln | Natural logarithm | \lnX | $ln {10}$ | LN 10 |
! | Factorial | 5! | $5!$ | Five factorial |
() | Parentheses | (2+1) | $(2+1)$ | Two plus one in parethesises |
\{ \} | $\{2+1\}$ | Open brace two plus one close brace |
Special mathematical symbols
Tag or symbol | Transform | Formula content example | Formula input example | Pronunciation |
\alpha | alpha | \alpha | $\alpha$ | α
|
\Alpha | \Alpha | $\Alpha$ | ||
\beta | beta | \beta | $\beta$ | β
|
\Beta | \Beta | $\Beta$ | ||
\gamma | gamma | \gamma | $\gamma$ | γ
|
\Gamma | \Gamma | $\Gamma$ | ||
\delta | delta | \delta | $\delta$ | Δ
|
\Delta | \Delta | $\Delta$ | ||
\infty | infinity (Chinese) | \infty | $\infty$ | Infinity
|
∞ | infty (English) | ∞ | $∞$ |
Geometry
Tag or symbol | Function | Formula content example | Formula input example | Pronunciation |
\pi | Dispatch | \pi=3.14159 | $\pi =3.14159$ | Pi equals 3.14159 |
\sin (sine | Trigonometric function | \sin (sine30^\circ=1\frac2 | $\sin 30^\circ =\frac {1}{2}$ | The sine of 30 degrees equals 1/2 |
\cos (cosine | $\cos 30^\circ =\frac {\sqrt {2}}{2}$ | The cosine of 30 degrees equals the square root of two over two | ||
\tan (tangent | $\tan 30^\circ =\frac {\sin 30^\circ}{\cos 30^\circ}$ | The tangent of 30 degrees equals the sine of 30 degrees over the cosine of 30 degrees | ||
\csc (cosecant | $\csc A$ | cosecant A | ||
\sec (secant | $\sec A$ | secant A | ||
\cot (cotangent | $\cot A$ | cotangent A | ||
\angle | Angle | \angle AB | $\angle AB$ | Angle AB |
∠ | ∠AB | $∠AB$ | ||
^\circ | Degree | ∠AB = 30^\circ | $∠AB = 30^\circ$ | Angle AB equals 30 degrees |
\odot | Circle | \odot | $\odot$ | Circle |
\overset\frown | Arc | \overset\frown {BC} | $\overset\frown {BC}$ | Arc BC |
\rm{Rt} | Right angle | \because \rm{Rt}\triangle ABC | $\because \rm{Rt}\triangle ABC$ | Because triangle ABC is a right triangle |
\mathrm{Rt} | \therefore AB \perp BC | $\therefore AB \perp BC$ | Therefore, AB is perpendicular to BC | |
\triangle | Triangle | \triangleABC | $\triangle ABC$ | Triangle ABC |
△ | △ABC | $△ABC$ | ||
\parallelogram | Parallelogram | \parallelogramABCD | $\parallelogram ABCD$ | Parallelogram ABCD |
\perp | Perpendicular | AB \perp BC | $AB \perp BC$ | AB is perpendicular to BC |
\bot | AB \bot BC | $AB \bot BC$ | ||
⊥ | AB ⊥ BC | $AB ⊥ BC$ | ||
\parallel | Parallel | A\parallel B | $A\parallel B$ | A is parallel to B |
\equalparallel | Parallel and equal to | A\equalparallel B | $A\equalparallel B$ | A is parallel and equal to B |
\cong | Congruent | △ABC\cong△DEF | $△ABC\cong△DEF$ | Triangle ABC is congruent to triangle DEF |
Conditions
Tag or symbol | Function | Formula content example | Formula input example | Pronunciation |
\implies | Launch | \implies 1+1=2 | $\implies 1+1=2$ | This implies that one plus one equals two |
\iff | Equivalent to | p\iffq | $p\iffq$ | p is equivalent to q |
\because | Because | \because a = b \therefore b=a | $\because a = b \therefore b=a$ | Because a equals b, b equals a |
\therefore | Therefore |
Units
Units must be wrapped in a \unit, \quantity, \mathit, \mathrm, or \rm tag. For example: \unit{cm}.
Tag or symbol | Pronunciation | Formula content example | Formula input example | Example pronunciation |
mm | millimeter | 5\quantity{mm} | $5\quantity{mm}$ | 5 millimeters |
cm | centimeter | 5\quantity{cm} | $5\quantity{cm}$ | 5 centimeters |
dm | decimeter | 5\quantity{dm} | $5\quantity{dm}$ | 5 decimeters |
m | meter | 5\quantity{m} | $5\quantity{m}$ | 5 meters |
km | kilometer | 5\quantity{km} | $5\quantity{km}$ | 5 kilometers |
g | gram | 5\quantity{g} | $5\quantity{g}$ | 5 grams |
kg | kilogram | 5\quantity{kg} | $5\quantity{kg}$ | 5 kilograms |
t | ton | 5\quantity{t} | $5\quantity{t}$ | 5 tons |
mm^2 | square millimeter | 5\quantity{mm^2} | $5\quantity{mm^2}$ | 5 square millimeters |
cm^2 | square centimeter | 5\quantity{cm^2} | $5\quantity{cm^2}$ | 5 square centimeters |
dm^2 | square decimeter | 5\quantity{dm^2} | $5\quantity{dm^2}$ | 5 square decimeters |
m^2 | square meter | 5\quantity{m^2} | $5\quantity{m^2}$ | 5 square meters |
km^2 | square kilometer | 5\quantity{km^2} | $5\quantity{km^2}$ | 5 square kilometers |
mm^3 | cubic millimeter | 5\quantity{mm^3} | $5\quantity{mm^3}$ | 5 cubic millimeters |
cm^3 | cubic centimeter | 5\quantity{cm^3} | $5\quantity{cm^3}$ | 5 cubic centimeters |
dm^3 | cubic decimeter | 5\quantity{dm^3} | $5\quantity{dm^3}$ | 5 cubic decimeters |
m^3 | cubic meter | 5\quantity{m^3} | $5\quantity{m^3}$ | 5 cubic meters |
km^3 | cubic kilometer | 5\quantity{km^3} | $5\quantity{km^3}$ | 5 cubic kilometers |
ml | milliliter | 5\quantity{ml} | $5\quantity{ml}$ | 5 milliliters |
s | second | 5\quantity{s} | $5\quantity{s}$ | 5 seconds |
min | minute | 5\quantity{min} | $5\quantity{min}$ | 5 minutes |
h | hour | 5\quantity{h} | $5\quantity{h}$ | 5 hours |
km/h | kilometers per hour | 5\quantity{km/h} | $5\quantity{km/h}$ | 5 kilometers per hour |
g/l | grams per liter | 5\quantity{g/l} | $5\quantity{g/l}$ | 5 grams per liter |
Limitations
Language limit: Only Chinese is supported.
Content limits:
Formulas must use only the tags and symbols listed in Supported tags and symbols.
Mathematical formulas in Markdown format, such as
```math ... ```, are not supported.Include only the formula within the separators. Other content may cause inaccurate speech synthesis.
Model availability:
cosyvoice-v2,cosyvoice-v3-flash, andcosyvoice-v3-plusare supported.
FAQ
Q: Why is the formula I entered not read?
Check the following items:
Check the separators: Confirm that the formula is correctly wrapped in
$...$,$$...$$,\(...\), or\[...\].Check the formula complexity: Make sure the formula does not contain unsupported tags or symbols. For more information, see Limitations and Supported tags and symbols.
Check for escape characters: When you send the API request, confirm that any backslash (
\) in the formula is correctly escaped as\\.
Q: How do I correctly handle strings that contain a \ (backslash) in my code?
In most programming languages, such as Python, Java, and JavaScript, the backslash (\) is a special escape character in string literals and JSON-formatted data. Therefore, you must escape the backslash itself. Use \\ to represent a single \. For example, write \frac as \\frac in your code.