### Install dependencies

Source: https://github.com/hotoo/pinyin/blob/master/DEVELOP.md

Run this command to install all project dependencies using pnpm.

```bash
pnpm i
```

--------------------------------

### Install pinyin CLI

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/cli/index.md

Install the package globally using npm.

```shell
npm i pinyin-cli -g
```

--------------------------------

### Install pinyin packages

Source: https://context7.com/hotoo/pinyin/llms.txt

Commands to install the core library or the CLI tool.

```bash
npm install pinyin --save
```

```bash
npm install pinyin-cli -g
```

--------------------------------

### Import Example Component

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/EXAMPLE.mdx

Import the Example component from its local path. This component is used for demonstrating pinyin conversion functionalities.

```tsx
import Example from '../../components/example/index.tsx';
```

--------------------------------

### Install pinyin via npm

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Use npm to install the pinyin package into your project.

```bash
npm install pinyin --save
```

--------------------------------

### Pinyin CLI Usage Examples

Source: https://context7.com/hotoo/pinyin/llms.txt

The `pinyin-cli` provides command-line access to pinyin conversion features, supporting various styles, modes, segmentation, heteronyms, and custom separators. Examples cover basic conversion to advanced options like grouping and help.

```bash
# Basic conversion
pinyin 中文
# Output: zhōng wén

# Different styles
pinyin -s NORMAL 中文
# Output: zhong wen

pinyin -s TONE2 中文
# Output: zhong1 wen2

pinyin -s FIRST_LETTER 中文
# Output: z w

# Surname mode
pinyin -m SURNAME 华罗庚
# Output: huà luó gēng

# With segmentation
pinyin -S 银行行长
# Output: yín háng háng zhǎng

# Heteronym output
pinyin -h 好
# Output: hǎo,hào

# Compact output with heteronyms
pinyin -h -c 好人
# Output: hǎo,rén hào,rén

# Custom separator
pinyin -p "-" 中文
# Output: zhōng-wén

# Group by phrases
pinyin -S -g 我喜欢你
# Output: wǒ xǐhuān nǐ

# Show help
pinyin --help
```

--------------------------------

### Example Component Usage for Pinyin Conversion

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/EXAMPLE.mdx

Render the Example component to provide an interface for Chinese to Pinyin conversion. Configure various output styles and options via the i18n prop.

```tsx
<Example i18n={{
  inputLabel: "Please input chinese",
  outputLabel: "Output pinyin",
  styleLabelNormal: "Normal Style",
  styleLabelTone: "Tone Style",
  styleLabelTone2: "Tone Style(tone2)",
  styleLabelTo3ne: "Tone Style(to3ne)",
  styleLabelInitials: "Initial Style",
  styleLabelFirstLetter: "First Letter Style",
  styleLabelPassport: "Passport Style",
  segmentLabel: "Segment",
  groupLabel: "Group Pinyin",
  compactLabel: "Compact Output",
  heteronymLabel: "Heteronym",
  modeLabel: "Name mode",
}} />
```

--------------------------------

### Configure Pinyin Output Styles

Source: https://context7.com/hotoo/pinyin/llms.txt

Examples of different output formats using the style option.

```typescript
import { pinyin } from "pinyin";

const text = "拼音";

// STYLE_TONE (default) - Tone marks on vowels
console.log(pinyin(text, { style: "tone" }));
// Output: [ [ 'pīn' ], [ 'yīn' ] ]

// STYLE_NORMAL - No tone marks
console.log(pinyin(text, { style: "normal" }));
// Output: [ [ 'pin' ], [ 'yin' ] ]

// STYLE_TONE2 - Tone number at end
console.log(pinyin(text, { style: "tone2" }));
// Output: [ [ 'pin1' ], [ 'yin1' ] ]

// STYLE_TO3NE - Tone number after vowel
console.log(pinyin(text, { style: "to3ne" }));
// Output: [ [ 'pi1n' ], [ 'yi1n' ] ]

// STYLE_INITIALS - Initial consonants only
console.log(pinyin(text, { style: "initials" }));
// Output: [ [ 'p' ], [ 'y' ] ]

// STYLE_FIRST_LETTER - First letter only
console.log(pinyin(text, { style: "first_letter" }));
// Output: [ [ 'p' ], [ 'y' ] ]

// STYLE_PASSPORT - Uppercase, ü becomes YU
console.log(pinyin("绿", { style: "passport" }));
// Output: [ [ 'LYU' ] ]
```

--------------------------------

### Sorting by Pinyin

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Provides examples of how to sort data using pinyin comparison.

```APIDOC
## Q&A

### How to sort by pinyin?

This module provide default compare implementation:

```javascript
const pinyin = require('pinyin');

const data = '我要排序'.split('');
const sortedData = data.sort(pinyin.compare);
```

But if you need different implementation, do it like:

```javascript
const pinyin = require('pinyin');

const data = '我要排序'.split('');

// Suggest you to store pinyin result by data persistence.
const pinyinData = data.map(han => ({
  han: han,
  pinyin: pinyin(han)[0][0], // Choose you options and styles.
}));
const sortedData = pinyinData.sort((a, b) => {
  return a.pinyin.localeCompare(b.pinyin);
}).map(d => d.han);
```
```

--------------------------------

### options.group explanation

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Enables grouping of Pinyin results by phrases, which requires segmentation to be active. An example shows grouped Pinyin for '我喜欢你'.

```markdown
### `<Boolean>` options.group

Group pinyin by phrases. for example:

```
我喜欢你
wǒ xǐhuān nǐ
```
```

--------------------------------

### Convert Chinese to Pinyin in TypeScript

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Examples of using the pinyin function with various options like heteronym, segmentation, grouping, and styles.

```typescript
import { pinyin } from "pinyin";

console.log(pinyin("中心"));    // [ [ 'zhōng' ], [ 'xīn' ] ]

console.log(pinyin("中心", {
  heteronym: true                // Enable heteronym mode.
}));                            // [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]

console.log(pinyin("中心", {
  heteronym: true,              // Enable heteronym mode.
  segment: true                 // Enable Chinese words segmentation, fix most heteronym problem.
}));                            // [ [ 'zhōng' ], [ 'xīn' ] ]

console.log(pinyin("我喜欢你", {
  segment: true,                // Enable segmentation. Needed for grouping.
  group: true                   // Group pinyin segments
}));                            // [ [ 'wǒ' ], [ 'xǐhuān' ], [ 'nǐ' ] ]

console.log(pinyin("中心", {
  style: pinyin.STYLE_INITIALS, // Setting pinyin style.
  heteronym: true
}));                            // [ [ 'zh' ], [ 'x' ] ]

console.log(pinyin("华夫人", {
  mode: "surname",              // 姓名模式。
}));                            // [ ['huà'], ['fū'], ['rén'] ]
```

--------------------------------

### Convert Chinese to Pinyin in TypeScript

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Examples of using the pinyin function with various options like heteronym support, segmentation, and custom styles.

```typescript
import { pinyin } from "pinyin";

console.log(pinyin("中心"));    // [ [ 'zhōng' ], [ 'xīn' ] ]

console.log(pinyin("中心", {
  heteronym: true,              // 启用多音字模式
}));                            // [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]

console.log(pinyin("中心", {
  heteronym: true,              // 启用多音字模式
  segment: true,                // 启用分词，以解决多音字问题。默认不开启，使用 true 开启使用 Intl.Segmenter 分词库。
}));                            // [ [ 'zhōng' ], [ 'xīn' ] ]

console.log(pinyin("中心", {
  segment: "@node-rs/jieba",    // 指定分词库，可以是 "Intl.Segmenter", "nodejieba"、"segmentit"、"@node-rs/jieba"。
}));                            // [ [ 'zhōng' ], [ 'xīn' ] ]

console.log(pinyin("我喜欢你", {
  segment: "segmentit",         // 启用分词
  group: true,                  // 启用词组
}));                            // [ [ 'wǒ' ], [ 'xǐhuān' ], [ 'nǐ' ] ]

console.log(pinyin("中心", {
  style: "initials",            // 设置拼音风格。
  heteronym: true,              // 即使有多音字，因为拼音风格选择，重复的也会合并。
}));                            // [ [ 'zh' ], [ 'x' ] ]

console.log(pinyin("华夫人", {
  mode: "surname",              // 姓名模式。
}));                            // [ ['huà'], ['fū'], ['rén'] ]
```

--------------------------------

### Compact Output Mode in Pinyin

Source: https://context7.com/hotoo/pinyin/llms.txt

Use the `compact` option to get all pronunciation combinations as flat arrays, useful for generating all variants of a phrase with heteronyms. This contrasts with the default nested array output.

```typescript
import { pinyin } from "pinyin";

// Without compact - nested arrays
const normalOutput = pinyin("你好吗", { heteronym: true });
console.log(normalOutput);
// Output: [ [ 'nǐ' ], [ 'hǎo', 'hào' ], [ 'ma', 'má', 'mǎ' ] ]

// With compact - all combinations as separate arrays
const compactOutput = pinyin("你好吗", { heteronym: true, compact: true });
console.log(compactOutput);
// Output: [
//   [ 'nǐ', 'hǎo', 'ma' ], [ 'nǐ', 'hǎo', 'má' ], [ 'nǐ', 'hǎo', 'mǎ' ],
//   [ 'nǐ', 'hào', 'ma' ], [ 'nǐ', 'hào', 'má' ], [ 'nǐ', 'hào', 'mǎ' ]
// ]
```

--------------------------------

### Sort Data by Pinyin

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Examples for sorting Chinese characters using the default comparator or a custom implementation.

```javascript
const pinyin = require('pinyin');

const data = '我要排序'.split('');
const sortedData = data.sort(pinyin.compare);
```

```javascript
const pinyin = require('pinyin');

const data = '我要排序'.split('');

// 建议将汉字的拼音持久化存储起来。
const pinyinData = data.map(han => ({
  han: han,
  pinyin: pinyin(han)[0][0], // 可以自行选择不同的生成拼音方案和风格。
}));
const sortedData = pinyinData.sort((a, b) => {
  return a.pinyin.localeCompare(b.pinyin);
}).map(d => d.han);
```

--------------------------------

### Sorting Chinese Text with pinyin.compare

Source: https://context7.com/hotoo/pinyin/llms.txt

The `compare` function is designed for sorting Chinese text alphabetically by pinyin and can be directly used with `Array.sort()`. A custom sorting example demonstrates more control using `pinyin` with `localeCompare`.

```typescript
import { pinyin, compare } from "pinyin";

// Sort Chinese characters alphabetically by pinyin
const characters = '我要排序'.split('');
const sorted = characters.sort(compare);
console.log(sorted.join(''));
// Output: 排我序要

// Custom sorting with more control
const words = ['北京', '上海', '广州', '深圳'];
const sortedWords = words.sort((a, b) => {
  const pyA = pinyin(a, { style: 'normal' }).flat().join('');
  const pyB = pinyin(b, { style: 'normal' }).flat().join('');
  return pyA.localeCompare(pyB);
});
console.log(sortedWords);
// Output: [ '北京', '广州', '上海', '深圳' ]
```

--------------------------------

### Run Tests with npm

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Execute the test suite for the pinyin module using npm.

```bash
npm test
```

--------------------------------

### CLI Options

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/cli/index.md

List of available command-line flags and their descriptions.

```text
  -h, --help                   output usage information
  -V, --version                output the version number
  -v, --version                output the version number
  -s, --style <style>          pinyin styles: [NORMAL,TONE,TONE2,INITIALS,FIRST_LETTER]
  -m, --mode <mode>            pinyin mode: [NORMAL,SURNAME]
  -S, --segment [segment]      segmentation word to phrases, support "Intl.Segmenter", "nodejieba", "@node-rs/jieba", "segmentit"
  -h, --heteronym              output heteronym pinyins
  -g, --group                  output group by phrases
  -c, --compact                output the compact pinyin result
  -p, --separator <separator>  separator between words
```

--------------------------------

### Lint project

Source: https://github.com/hotoo/pinyin/blob/master/DEVELOP.md

Execute the linting process across the monorepo using Turbo.

```bash
turbo lint
```

--------------------------------

### Run tests

Source: https://github.com/hotoo/pinyin/blob/master/DEVELOP.md

Execute the test suite for the monorepo using Turbo.

```bash
turbo test
```

--------------------------------

### Testing the Module

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Instructions on how to run tests for the pinyin module.

```APIDOC
## Test

```javascript
npm test
```
```

--------------------------------

### Configure Compact Mode

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Demonstrates the difference between standard and compact output modes when handling polyphonic characters.

```javascript
pinyin("你好吗", { compact:false });
> [[nǐ], [hǎo,hào], [ma,má,mǎ]]

pinyin("你好吗", { compact:true });
> [
>   [nǐ,hǎo,ma], [nǐ,hǎo,má], [nǐ,hǎo,mǎ],
>   [nǐ,hào,ma], [nǐ,hào,má], [nǐ,hào,mǎ],
> ]
```

--------------------------------

### options.style explanation

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Specifies the desired Pinyin output style using static properties like `STYLE_*`. The default style is `STYLE_TONE`.

```markdown
### `<Object>` options.style

Specify pinyin style. please use static properties like `STYLE_*`.
default is `.STYLE_TONE`. see Static Property for more.
```

--------------------------------

### Use pinyin via CLI

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Command line usage for converting text to pinyin.

```bash
$ pinyin 中心
zhōng xīn
$ pinyin -h
```

--------------------------------

### Basic Usage

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/cli/index.md

Convert Chinese characters to pinyin or display help information.

```shell
pinyin 中文

# more usage see:
pinyin -h
```

--------------------------------

### Define IPinyinStyle Options Reference

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Reference for available Pinyin styles.

```typescript
IPinyinStyle =
  "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport" | // 推荐使用小写，和输出的拼音一致
  "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT" | // 方便老版本迁移
  0        | 1      | 2       | 5       | 3          | 4;               // 兼容老版本
```

--------------------------------

### pinyin.compare(a, b)

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Default compare implementation for pinyin.

```APIDOC
## pinyin.compare(a, b)

### Description
Provides a default comparison implementation for pinyin strings.

### Parameters
#### Request Body
- **a** (String) - Required - First pinyin string.
- **b** (String) - Required - Second pinyin string.

### Response
#### Success Response (200)
- **result** (Number) - Comparison result.
```

--------------------------------

### Project Directory Structure

Source: https://github.com/hotoo/pinyin/blob/master/README.en_US.md

This is the directory structure of the Hotoo Pinyin monorepo. It outlines the organization of applications, core packages, CLI tools, and other utilities.

```bash
|- apps/
|  `- website               // document website.
|- packages/
|  |- pinyin/               // pinyin main reposition.
|  |- pinyin-cli/           // command line tool of pinyin, install it global and use every where.
|  |- pinyin-react/         // React version of pinyin, Coming soon.
|  `-tools/                 // misc tools for this reposition.
|- package.json
`- README.md
```

--------------------------------

### Pinyin Styles and Modes

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Explains the different styles and modes supported by the pinyin module.

```APIDOC
## Pinyin Styles and Modes

### `.STYLE_INITIALS`

Initial consonant (of a Chinese syllable).

Example: pinyin of `中国` is `zh g`

Note: when a Han （汉字） without initial consonant, will convert to empty string.

### `.STYLE_FIRST_LETTER`

First letter style.

Example: `p y`

### `pinyin.MODE_NORMAL`

Normal mode. This is the default mode.

### `pinyin.MODE_SURNAME`

Surname mode. If chinese word is surname, The pinyin of surname is prioritized.
```

--------------------------------

### options.heteronym explanation

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Controls whether heteronym mode is enabled. When enabled, all possible Pinyin pronunciations for a character are returned.

```markdown
### `<Boolean>` options.heteronym

Enable or disable heteronym mode. default is disabled, `false`.
```

--------------------------------

### options.mode explanation

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Sets the Pinyin conversion mode. The default is `MODE_NORMAL`, but `MODE_SURNAME` can be used for surname-specific scenarios.

```markdown
### `options.mode`

pinyin mode, default is `pinyin.MODE_NORMAL`. If you cleared in surname scene, use `pinyin.MODE_SURNAME` maybe better.
```

--------------------------------

### Initialize Pinyin Table Component

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/pinyin-table.mdx

Configure the Pinyin Table with localized labels for initials and finals.

```tsx
<PinyinTable i18n={{
  initials: "Initials",
  finals: "Finals",
  medial_vowels_i: "Medial Vowels (i)",
  medial_vowels_u: "Medial Vowels (u)",
  medial_vowels_v: "Medial Vowels (ü)",
}} />
```

--------------------------------

### options.segment explanation

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Enables Chinese word segmentation to improve heteronym accuracy, but may increase performance overhead and resource consumption.

```markdown
#### `<Boolean>` options.segment

Enable Chinese word segmentation. Segmentation is helpful for fix heteronym
problem, but performance will be more slow, and need more CPU and memory.

Default is `false`.
```

--------------------------------

### Core API: pinyin(words, options)

Source: https://context7.com/hotoo/pinyin/llms.txt

The main function converts Chinese characters to pinyin. It returns a 2D array where each inner array contains possible pronunciations for each character, which is useful for handling heteronyms.

```APIDOC
## Core API: pinyin(words, options)

### Description
The main function converts Chinese characters to pinyin, returning a 2D array where each inner array contains possible pronunciations for each character (useful for heteronyms).

### Method
`pinyin(words: string, options?: PinyinOptions): string[][]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { pinyin } from "pinyin";

// Basic usage - converts each character to pinyin with tone marks
const result = pinyin("中心");
console.log(result);
// Output: [ [ 'zhōng' ], [ 'xīn' ] ]

// With heteronym mode - returns all possible pronunciations
const heteronymResult = pinyin("中心", { heteronym: true });
console.log(heteronymResult);
// Output: [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]

// With segmentation - fixes heteronym problems by understanding word context
const segmentResult = pinyin("中心", {
  heteronym: true,
  segment: true
});
console.log(segmentResult);
// Output: [ [ 'zhōng' ], [ 'xīn' ] ]

// Group pinyin by phrases - combines multi-character words
const groupResult = pinyin("我喜欢你", {
  segment: true,
  group: true
});
console.log(groupResult);
// Output: [ [ 'wǒ' ], [ 'xǐhuān' ], [ 'nǐ' ] ]
```

### Response
#### Success Response (200)
- **pinyin_array** (string[][]) - A 2D array of pinyin pronunciations for the input Chinese characters.
```

--------------------------------

### Transform Chinese to pinyin

Source: https://github.com/hotoo/pinyin/blob/master/packages/pinyin-cli/README.md

Basic command to convert Chinese characters to pinyin output.

```shell
pinyin 中文
```

--------------------------------

### Static Property .STYLE_NORMAL

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Represents the normal Pinyin output style, which is typically space-separated syllables without tones.

```markdown
### `.STYLE_NORMAL`

Normal mode.

Example: `pin yin`
```

--------------------------------

### Sort Chinese Characters by Pinyin (Custom Implementation)

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Implement custom sorting logic for Chinese characters based on their pinyin. This approach involves extracting pinyin, storing it alongside the character, and then sorting based on the extracted pinyin using localeCompare. It offers more control over the sorting process.

```javascript
const pinyin = require('pinyin');

const data = '我要排序'.split('');

// Suggest you to store pinyin result by data persistence.
const pinyinData = data.map(han => ({
  han: han,
  pinyin: pinyin(han)[0][0], // Choose you options and styles.
}));
const sortedData = pinyinData.sort((a, b) => {
  return a.pinyin.localeCompare(b.pinyin);
}).map(d => d.han);
```

--------------------------------

### Configure Segmentation Engines

Source: https://context7.com/hotoo/pinyin/llms.txt

Specifying different segmentation engines to improve heteronym accuracy.

```typescript
import { pinyin } from "pinyin";

// Enable default segmentation (Intl.Segmenter)
const result1 = pinyin("重要", { segment: true });
console.log(result1);
// Output: [ [ 'zhòng' ], [ 'yào' ] ]

// Specify segmentation engine explicitly
// Options: "Intl.Segmenter", "nodejieba", "@node-rs/jieba", "segmentit"
const result2 = pinyin("长大", { segment: "Intl.Segmenter" });
console.log(result2);
// Output: [ [ 'zhǎng' ], [ 'dà' ] ]

// For Node.js with nodejieba (requires separate installation)
// npm install @node-rs/jieba
const result3 = pinyin("银行行长", { segment: "@node-rs/jieba" });
console.log(result3);
// Output: [ [ 'yín' ], [ 'háng' ], [ 'háng' ], [ 'zhǎng' ] ]
```

--------------------------------

### Pinyin Static Properties

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Constants for different Pinyin styles and modes.

```APIDOC
## Pinyin Static Properties

### Description
Constants for specifying Pinyin output styles and modes.

### Properties
#### Style Constants
- **`.STYLE_NORMAL`**: Normal mode. Example: `pin yin`
- **`.STYLE_TONE`**: Tone style (default). Example: `pīn yīn`
- **`.STYLE_TONE2`**: Tone style by postfix number [0-4]. Example: `pin1 yin1`
- **`.STYLE_TO3NE`**: Tone style by number [0-4] after phonetic notation character. Example: `pin1 yin1`
- **`.STYLE_INITIALS`**: Initials of Pinyin. Example: `zh x`
- **`.STYLE_FIRST_LETTER`**: First letter of Pinyin. Example: `z x`

#### Mode Constants
- **`.MODE_NORMAL`**: Default mode.
- **`.MODE_SURNAME`**: Surname mode, useful for Chinese surnames.
```

--------------------------------

### Generating All Pinyin Combinations with compact(arr)

Source: https://context7.com/hotoo/pinyin/llms.txt

The `compact` utility function converts nested pinyin arrays into arrays of all possible combinations. This is useful when dealing with phrases containing multiple heteronyms.

```typescript
import { pinyin, compact } from "pinyin";

// Get heteronym results
const heteronymResult = pinyin("好", { heteronym: true });
console.log(heteronymResult);
// Output: [ [ 'hǎo', 'hào' ] ]

// Build phrase with multiple heteronyms
const phrase = [
  pinyin("好", { heteronym: true })[0],  // [ 'hǎo', 'hào' ]
  pinyin("人", { heteronym: true })[0]   // [ 'rén' ]
];
const allCombinations = compact([phrase[0], phrase[1]]);
console.log(allCombinations);
// Output: [ [ 'hǎo', 'rén' ], [ 'hào', 'rén' ] ]
```

--------------------------------

### Pinyin Comparison API

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Provides a default algorithm for sorting strings based on their Pinyin representation.

```APIDOC
## POST /api/pinyin/compare

### Description
Compares two strings based on their Pinyin representation using the default sorting algorithm.

### Method
POST

### Endpoint
/api/pinyin/compare

### Parameters
#### Request Body
- **a** (string) - Required - The first string to compare.
- **b** (string) - Required - The second string to compare.

### Request Example
```json
{
  "a": "你好",
  "b": "世界"
}
```

### Response
#### Success Response (200)
- **comparisonResult** (number) - A number indicating the comparison result: -1 if a < b, 0 if a == b, 1 if a > b.

#### Response Example
```json
{
  "comparisonResult": -1
}
```
```

--------------------------------

### Pinyin Comparison API

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/api/v4/index.md

Provides a default algorithm for sorting strings based on their Pinyin representation.

```APIDOC
## Method `compare(a, b)`

### Description
Provides the default algorithm for sorting based on Pinyin.

### Parameters
#### Path Parameters
- **a** (string) - The first string to compare.
- **b** (string) - The second string to compare.

### Response
#### Success Response (200)
- **result** (Number) - Returns a negative value if a < b, zero if a = b, and a positive value if a > b, based on Pinyin sorting.

### Response Example
```json
{
  "result": -1 
}
```
```

--------------------------------

### Static Property .STYLE_TO3NE

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Represents a Pinyin output style where tones are indicated by numbers (0-4) placed after the phonetic notation character.

```markdown
### `.STYLE_TO3NE`

tone style by number [0-4] after phonetic notation character.

Example: `pin1 yin1`
```

--------------------------------

### Static Property .STYLE_TONE2

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Represents a Pinyin output style where tones are indicated by numbers (0-4) appended to each syllable.

```markdown
### `.STYLE_TONE2`

tone style by postfix number [0-4].

Example: `pin1 yin1`
```

--------------------------------

### Static Property .STYLE_TONE

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Represents the default Pinyin output style, which includes tone marks above the vowels.

```markdown
### `.STYLE_TONE`

Tone style, this is default.

Example: `pīn yīn`
```

--------------------------------

### Define IPinyinStyle Type

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Supported Pinyin output formats.

```typescript
export type IPinyinStyle =
  "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport" | // 推荐使用小写，和输出的拼音一致
  "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT" | // 方便老版本迁移
  0        | 1      | 2       | 5       | 3          | 4;               // 兼容老版本
```

--------------------------------

### pinyin(words[, options])

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

Converts Chinese characters to pinyin based on the provided options.

```APIDOC
## pinyin(words[, options])

### Description
Convert Han (汉字) to pinyin. Returns an Array of Arrays of Strings. If a character is a heteronym, it will contain multiple pinyin values.

### Parameters
#### Request Body
- **words** (String) - Required - The Chinese characters to convert.
- **options** (IPinyinOptions) - Optional - Configuration object for pinyin conversion.

### Response
#### Success Response (200)
- **result** (Array<Array<String>>) - The converted pinyin representation.

### Request Example
```typescript
pinyin("中心", {
  heteronym: true,
  segment: true
});
```
```

--------------------------------

### Pinyin Compact API

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Transforms multi-syllable Pinyin results into a compact form, exploring various combinations.

```APIDOC
## POST /api/pinyin/compact

### Description
Transforms a 2D Pinyin array into a compact form, generating all possible combinations of multi-syllable Pinyin.

### Method
POST

### Endpoint
/api/pinyin/compact

### Parameters
#### Request Body
- **pinyinResult** (Array<Array<string>>) - Required - The 2D Pinyin array to compact.

### Request Example
```json
{
  "pinyinResult": [
    [ "zhōng", "zhòng" ],
    [ "xīn" ]
  ]
}
```

### Response
#### Success Response (200)
- **compactedPinyin** (Array<Array<string>>) - A 2D array representing the compacted Pinyin combinations.

#### Response Example
```json
{
  "compactedPinyin": [
    [ "zhōng", "xīn" ],
    [ "zhòng", "xīn" ]
  ]
}
```
```

--------------------------------

### Pinyin Compact API

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/api/v4/index.md

Transforms Pinyin heteronyms into compact combinations.

```APIDOC
## Method `compact(pinyinResult array[][])`

### Description
Transforms Pinyin heteronyms into compact combinations. Refer to `options.compact` for details.

### Parameters
#### Path Parameters
- **pinyinResult** (Array<Array<string>>) - The two-dimensional array of Pinyin results, potentially containing heteronyms.

### Response
#### Success Response (200)
- **result** (Array<Array<string>>) - A two-dimensional array with Pinyin heteronyms arranged in compact combinations.

### Response Example
```json
{
  "result": [
    [ "zhōng" ],
    [ "xīn" ]
  ]
}
```
```

--------------------------------

### Enable heteronym mode

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Convert Chinese characters to Pinyin with heteronyms enabled. This option returns all possible Pinyin pronunciations for characters that have multiple readings.

```typescript
console.log(pinyin("中心", {
  heteronym: true                // Enable heteronym mode.
}));                            // [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]
```

--------------------------------

### Pinyin Styles

Source: https://context7.com/hotoo/pinyin/llms.txt

The `style` option controls the output format of pinyin. Six styles are available for different use cases.

```APIDOC
## Pinyin Styles

### Description
The `style` option controls the output format of pinyin. Six styles are available for different use cases.

### Method
`pinyin(words: string, options: { style: PinyinStyle }): string[][]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { pinyin } from "pinyin";

const text = "拼音";

// STYLE_TONE (default) - Tone marks on vowels
console.log(pinyin(text, { style: "tone" }));
// Output: [ [ 'pīn' ], [ 'yīn' ] ]

// STYLE_NORMAL - No tone marks
console.log(pinyin(text, { style: "normal" }));
// Output: [ [ 'pin' ], [ 'yin' ] ]

// STYLE_TONE2 - Tone number at end
console.log(pinyin(text, { style: "tone2" }));
// Output: [ [ 'pin1' ], [ 'yin1' ] ]

// STYLE_TO3NE - Tone number after vowel
console.log(pinyin(text, { style: "to3ne" }));
// Output: [ [ 'pi1n' ], [ 'yi1n' ] ]

// STYLE_INITIALS - Initial consonants only
console.log(pinyin(text, { style: "initials" }));
// Output: [ [ 'p' ], [ 'y' ] ]

// STYLE_FIRST_LETTER - First letter only
console.log(pinyin(text, { style: "first_letter" }));
// Output: [ [ 'p' ], [ 'y' ] ]

// STYLE_PASSPORT - Uppercase, ü becomes YU
console.log(pinyin("绿", { style: "passport" }));
// Output: [ [ 'LYU' ] ]
```

### Response
#### Success Response (200)
- **pinyin_array** (string[][]) - A 2D array of pinyin pronunciations formatted according to the specified style.
```

--------------------------------

### Enable segmentation for heteronyms

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Convert Chinese characters to Pinyin with both heteronym mode and segmentation enabled. Segmentation helps resolve most heteronym issues by identifying words.

```typescript
console.log(pinyin("中心", {
  heteronym: true,
  segment: true                 // Enable Chinese words segmentation, fix most heteronym problem.
}));                            // [ [ 'zhōng' ], [ 'xīn' ] ]
```

--------------------------------

### pinyin.compare function API

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Provides a default comparison implementation for Pinyin strings, useful for sorting purposes.

```typescript
`Number` pinyin.compare(a, b)
```

--------------------------------

### Define IPinyinOptions Interface

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

TypeScript interface definition for the options argument of the pinyin method.

```typescript
export interface IPinyinOptions {
  style?: IPinyinStyle; // output style of pinyin.
  mode?: IPinyinMode, // mode of pinyin.
  segment?: IPinyinSegment | boolean;
  heteronym?: boolean;
  group?: boolean;
  compact?: boolean;
}
```

--------------------------------

### Convert to initials style

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Convert Chinese characters to Pinyin, outputting only the initial consonant of each syllable. Heteronym mode is also enabled.

```typescript
console.log(pinyin("中心", {
  style: pinyin.STYLE_INITIALS, // Setting pinyin style.
  heteronym: true
}));                            // [ [ 'zh' ], [ 'x' ] ]
```

--------------------------------

### Convert Chinese to Pinyin

Source: https://context7.com/hotoo/pinyin/llms.txt

Basic usage of the pinyin function, including heteronym handling, segmentation, and grouping.

```typescript
import { pinyin } from "pinyin";

// Basic usage - converts each character to pinyin with tone marks
const result = pinyin("中心");
console.log(result);
// Output: [ [ 'zhōng' ], [ 'xīn' ] ]

// With heteronym mode - returns all possible pronunciations
const heteronymResult = pinyin("中心", { heteronym: true });
console.log(heteronymResult);
// Output: [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]

// With segmentation - fixes heteronym problems by understanding word context
const segmentResult = pinyin("中心", {
  heteronym: true,
  segment: true
});
console.log(segmentResult);
// Output: [ [ 'zhōng' ], [ 'xīn' ] ]

// Group pinyin by phrases - combines multi-character words
const groupResult = pinyin("我喜欢你", {
  segment: true,
  group: true
});
console.log(groupResult);
// Output: [ [ 'wǒ' ], [ 'xǐhuān' ], [ 'nǐ' ] ]
```

--------------------------------

### Pinyin Comparison API

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Provides a default comparison function for Pinyin strings.

```APIDOC
## pinyin.compare(a, b)

### Description
Default compare implementation for pinyin.

### Method
`pinyin.compare`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
pinyin.compare("zhōng", "xīn");
```

### Response
#### Success Response (200)
- **Number** - Returns a number indicating the comparison result (e.g., -1, 0, 1).

#### Response Example
```json
{
  "result": -1
}
```
```

--------------------------------

### Define IPinyinStyle Types

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/api/v4/index.md

TypeScript type definition for supported pinyin output styles.

```typescript
export type IPinyinStyle =
  "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | // Suggest.
  "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" |
  0        | 1      | 2       | 5       | 3          | 4;               // compatibility.
```

--------------------------------

### Use Surname Mode

Source: https://context7.com/hotoo/pinyin/llms.txt

Adjusting pronunciation for Chinese names using the surname mode.

```typescript
import { pinyin } from "pinyin";

// Default mode - uses common pronunciation
const normalResult = pinyin("华夫人");
console.log(normalResult);
// Output: [ [ 'huá' ], [ 'fū' ], [ 'rén' ] ]

// Surname mode - uses surname-specific pronunciation
const surnameResult = pinyin("华夫人", { mode: "surname" });
console.log(surnameResult);
// Output: [ [ 'huà' ], [ 'fū' ], [ 'rén' ] ]

// Handles compound surnames automatically
const compoundSurname = pinyin("欧阳修", { mode: "surname" });
console.log(compoundSurname);
// Output: [ [ 'ōu' ], [ 'yáng' ], [ 'xiū' ] ]
```

--------------------------------

### Convert using surname mode

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Convert Chinese characters to Pinyin using the surname mode. This mode is optimized for handling Chinese surnames.

```typescript
console.log(pinyin("华夫人", {
  mode: "surname",              // 姓名模式。
}));                            // [ ['huà'], ['fū'], ['rén'] ]
```

--------------------------------

### Segmentation Options

Source: https://context7.com/hotoo/pinyin/llms.txt

Word segmentation improves accuracy for heteronyms by understanding word boundaries. Multiple segmentation engines are supported.

```APIDOC
## Segmentation Options

### Description
Word segmentation improves accuracy for heteronyms by understanding word boundaries. Multiple segmentation engines are supported.

### Method
`pinyin(words: string, options: { segment: boolean | string }): string[][]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { pinyin } from "pinyin";

// Enable default segmentation (Intl.Segmenter)
const result1 = pinyin("重要", { segment: true });
console.log(result1);
// Output: [ [ 'zhòng' ], [ 'yào' ] ]

// Specify segmentation engine explicitly
// Options: "Intl.Segmenter", "nodejieba", "@node-rs/jieba", "segmentit"
const result2 = pinyin("长大", { segment: "Intl.Segmenter" });
console.log(result2);
// Output: [ [ 'zhǎng' ], [ 'dà' ] ]

// For Node.js with nodejieba (requires separate installation)
// npm install @node-rs/jieba
const result3 = pinyin("银行行长", { segment: "@node-rs/jieba" });
console.log(result3);
// Output: [ [ 'yín' ], [ 'háng' ], [ 'háng' ], [ 'zhǎng' ] ]
```

### Response
#### Success Response (200)
- **pinyin_array** (string[][]) - A 2D array of pinyin pronunciations with word segmentation applied.
```

--------------------------------

### TypeScript Types for Pinyin Options

Source: https://context7.com/hotoo/pinyin/llms.txt

The library exports comprehensive TypeScript types for all options and return values, including `IPinyinOptions`, `IPinyinStyle`, `IPinyinMode`, and `IPinyinSegment`. This allows for strongly typed usage of the pinyin function.

```typescript
import { pinyin } from "pinyin";
import type { IPinyinOptions, IPinyinStyle, IPinyinMode, IPinyinSegment } from "pinyin";

// Full typed options
const options: IPinyinOptions = {
  style: "tone",           // IPinyinStyle
  mode: "normal",          // IPinyinMode
  segment: true,           // boolean | IPinyinSegment
  heteronym: false,        // boolean
  group: false,            // boolean
  compact: false           // boolean
};

const result: string[][] = pinyin("测试", options);
console.log(result);
// Output: [ [ 'cè' ], [ 'shì' ] ]

// Style constants are also available
console.log(pinyin.STYLE_TONE);      // 1
console.log(pinyin.STYLE_NORMAL);    // 0
console.log(pinyin.MODE_NORMAL);     // 0
console.log(pinyin.MODE_SURNAME);    // 1
```

--------------------------------

### Define IPinyinMode Type

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Supported Pinyin modes.

```typescript
// - NORMAL: 普通模式
// - SURNAME: 姓氏模式，优先使用姓氏的拼音。
export type IPinyinMode =
  "normal" | "surname" |
  "NORMAL" | "SURNAME";
```

--------------------------------

### IPinyinMode type definition

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/en-US/index.md

Defines the possible modes for Pinyin conversion, specifically 'normal' for general use and 'surname' for handling Chinese surnames.

```typescript
export type IPinyinMode =
  "normal" | "surname" |
  "NORMAL" | "SURNAME";
```

--------------------------------

### Surname Mode

Source: https://context7.com/hotoo/pinyin/llms.txt

The `mode` option with value `"surname"` handles Chinese names correctly, using surname-specific pronunciations for characters that have different readings in personal names.

```APIDOC
## Surname Mode

### Description
The `mode` option with value `"surname"` handles Chinese names correctly, using surname-specific pronunciations for characters that have different readings in personal names.

### Method
`pinyin(words: string, options: { mode: "surname" }): string[][]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { pinyin } from "pinyin";

// Default mode - uses common pronunciation
const normalResult = pinyin("华夫人");
console.log(normalResult);
// Output: [ [ 'huá' ], [ 'fū' ], [ 'rén' ] ]

// Surname mode - uses surname-specific pronunciation
const surnameResult = pinyin("华夫人", { mode: "surname" });
console.log(surnameResult);
// Output: [ [ 'huà' ], [ 'fū' ], [ 'rén' ] ]

// Handles compound surnames automatically
const compoundSurname = pinyin("欧阳修", { mode: "surname" });
console.log(compoundSurname);
// Output: [ [ 'ōu' ], [ 'yáng' ], [ 'xiū' ] ]
```

### Response
#### Success Response (200)
- **pinyin_array** (string[][]) - A 2D array of pinyin pronunciations, with surname-specific readings applied where applicable.
```

--------------------------------

### Pinyin Conversion API

Source: https://github.com/hotoo/pinyin/blob/master/apps/website/docs/zh-CN/index.md

Converts Chinese characters to Pinyin with various options for style, heteronyms, and segmentation.

```APIDOC
## POST /api/pinyin

### Description
Converts Chinese characters to Pinyin.

### Method
POST

### Endpoint
/api/pinyin

### Parameters
#### Request Body
- **words** (string) - Required - The Chinese characters to convert.
- **options** (object) - Optional - Configuration options for Pinyin conversion.
  - **style** (IPinyinStyle) - Optional - The desired Pinyin output style (e.g., 'normal', 'tone', 'initials'). Defaults to 'tone'.
  - **mode** (IPinyinMode) - Optional - The Pinyin mode (e.g., 'normal', 'surname'). Defaults to 'normal'.
  - **segment** (IPinyinSegment | boolean) - Optional - Enables or specifies the segmentation library for better multi-syllable handling. Defaults to false.
  - **heteronym** (boolean) - Optional - Enables multi-syllable (heteronym) mode. Defaults to false.
  - **group** (boolean) - Optional - Groups Pinyin by word phrases. Defaults to false.
  - **compact** (boolean) - Optional - Compacts multi-syllable Pinyin. Defaults to false.

### Request Example
```json
{
  "words": "中心",
  "options": {
    "heteronym": true,
    "style": "tone"
  }
}
```

### Response
#### Success Response (200)
- **pinyinResult** (Array<Array<string>>) - A 2D array where each inner array contains the Pinyin for a character, potentially including multiple options for heteronyms.

#### Response Example
```json
{
  "pinyinResult": [
    [ "zhōng" ],
    [ "xīn" ]
  ]
}
```
```