# vLabeler

[![Discord](https://img.shields.io/discord/984044285584359444?style=for-the-badge&label=discord&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/yrTqG2SrRd)

选择语言：[English](../README.md) | [简体中文](README-zhCN.md) | [日本語](README-ja.md) | [한국어](README-ko.md)

`vLabeler` 是一个开源的语音标注应用程序，旨在提供：

- 现代，流畅的 UI/UX
- 可定制的标注流程，以供多个语音合成软件使用
- 高性能的多平台支持

如需帮助、建议、问题报告等，请加入我们的 [Discord](https://discord.gg/yrTqG2SrRd)。**

<details>
<summary>Demo 视频（英语）</summary>

请注意，由于此演示视频基于1.0.0-beta1，部分UI可能与最新版本不同。

[YouTube](https://youtu.be/xFX8SRrJEzM) | [bilibili](https://www.bilibili.com/video/BV1Ve4y1S7FF)
</details>

## 下载

请参阅 [Releases](https://github.com/sdercolin/vlabeler/releases)。

Releases 中提供了适用于以下平台的应用程序包。

- Windows: `~win64.zip`
- macOS (Intel): `~mac-x64.dmg`
- macOS (Apple Silicon): `~mac-arm64.dmg`
- Ubuntu: `~amd64.deb`

对于其他类型的 Linux 操作系统，您可能需要自己进行构建。

## 构建

vLabeler 基于 [Compose Multiplatform](https://github.com/JetBrains/compose-jb) 开发。
您可以使用 Gradle
来构建应用。[查看更多](https://github.com/JetBrains/compose-jb/tree/master/tutorials/Native_distributions_and_local_execution)

目前不支持跨平台构建。您只能构建适用于您的操作系统的应用程序包。

请确保您有 **JDK 17+** 用于构建。

```
// 构建安装包
./gradlew packageDistributionForCurrentOS

// 或者，构建可执行程序
./gradlew createDistributable
```

## 使用场景

vLabeler 的许多行为都依赖于可定制的 `标注器`。

目前，vLabeler 提供了以下内建标注器：

#### 处理 UTAU 的原音设定文件

![](utau-singer.gif)

适用于 UTAU 原音设定的的内建标注器有以下两项：

- UTAU oto 标注器

  如果您只想编辑一个 `oto.ini` 文件，请使用此标注器。

- UTAU singer 标注器

  如果您想编辑一个歌手声库下的多个 oto.ini 文件，请使用此标注器。
  请在创建项目时将 `采样目录`设置为歌手的根文件夹（通常包含一个 `character.txt` 文件）。

#### 处理音频分割标注文件

![](nnsvs-singer.gif)

对于 NNSVS/ENUNU 和类似语音合成系统中使用的标注文件，您可以使用以下选项：

- Sinsy lab 标注器

  此标注器适用于 Sinsy (NNSVS/ENUNU) 格式的 lab 文件，它使用 `100ns` 作为时间单位，使用 ` `（空格）作为分隔符。
  每个项目只接受一个标注文件。wav 文件通过文件名绑定到标注文件，例如，
  如果输入标注文件是 `foo.lab`，则将从 `采样目录` 中选择名为 `foo.wav` 的 wav 文件。

- Audacity 标注器

  此标注器适用于 Audacity 创建的 `Labels` 文件，它使用 `s` 作为时间单位，并使用 `\t` (tab) 作为分隔符。
  每个项目只接受一个标注文件。wav 文件通过文件名绑定到标注文件。
  例如，如果输入标注文件是 `foo.txt`，则会从 `Sample Directory` 中选择名为 `foo.wav` 的 wav 文件。

- NNSVS singer 标注器

  此标注器与 `Sinsy lab 标注器` 基本相同，但可以处理多个标注文件。
  通常，如果您的文件结构如下：
  ```
  - singer
      - wav
        - 1.wav
        - 2.wav
      - lab
        - 1.lab
        - 2.lab
  ```
  您可以通过将 `采样目录` 设置为 `singer` 文件夹来创建包含所有 lab 文件的项目。
  您可以在标注器的设置中更改 `wav` 和 `lab` 文件夹名称。

#### 其他（非内建）

- TextGrid labeler (for Praat TextGrid files): [GitHub](https://github.com/sdercolin/vlabeler-textgrid)

## 基本使用流程

1. 点击 `新建项目...`
2. 选择 `采样目录` 为您的音频文件所在的文件夹
3. 您可以按需更改 `项目名`
4. 选择一个标注器。请参阅 [使用场景](#使用场景) 来帮助您选择正确的标注器
5. 选择一个适合您的项目创建方式。大多数情况下选择 `默认` 即可
6. 如果您想导入单个文件作为输入，请选择 `文件` 并设置文件路径。某些标注器不支持此选项
7. 如果您想使用插件生成标注文件的模版，请选择 `模板生成器` 并设置插件
8. 点击 `完成`，开始编辑
9. 点击菜单中的 `导出`，得到编辑后的标注文件

如果您需要更多的自定义设置，请查看被折叠的`高级设置`，以及由标注器/模板生成器提供的设置。

## 开始快捷编辑

某些标注器支持 `快捷编辑` 功能，它允许您只使用单个文件或文件夹作为输入开始编辑。其他设置由标注器自动设置。

您可以在开始页面的 `快捷编辑` 列表中点击项目，并选择文件或文件夹开始快捷编辑。

在通过快捷编辑创建的项目中：

- 默认情况下启用自动导出，这意味着当您保存项目时，标注文件会被自动保存
- 重复使用快捷编辑时，项目文件可能会被静默地覆盖
- 除非标注器的作者将某些设置配置为特定值以供快捷编辑使用，否则将使用保存的标注器设置
- 您仍然可以在 `文件` -> `项目设置...` 中更改某些设置

## 可用的键盘/鼠标操作

请注意，如果您使用的是 macOS，则以下的 `Ctrl` 指的是 `Command`。

您可以在 `设置` -> `偏好设置` -> `键位映射` 中更改快捷键设置。

### 移动参数线

- 鼠标拖动普通参数线：移动它自己
- 鼠标拖动主要参数线：同时移动所有参数线
- `Shift`：反转普通/主要。例如，按住 Shift 键的同时拖动主要参数线，只会移动它自身
- `Q`/`W`/`E`/`R`/... ：将对应的参数线移动到当前光标位置。顺序在标注器中定义。请注意，此功能仅在单条目编辑模式下可用。

### 音频播放

- `Space`：播放当前条目，如果已经在播放，则停止播放
- `Shift` + `Space`：播放当前采样文件，如果已经在播放，则停止播放
- `Ctrl` + `Shift` + `Space`: 播放当前屏幕显示的范围，如果已经在播放，则停止播放
- （适用于大部分的工具）鼠标右键点击：播放点击的部分
- （适用于**光标**工具）`Alt` + 鼠标拖动参数：移动的同时播放光标位置附近的音频

另请参阅 [播放工具](#播放) 的章节以了解更多的操作。

### 滚动

- `Shift` + 鼠标滚轮滚动：水平滚动
- `F` 或底部栏中央的焦点按钮：滚动以使当前条目在屏幕上居中

### 放大/缩小

- `=` 或底部栏中的 `+` 按钮：放大
- `=` 或底部栏中的 `-` 按钮：缩小
- `Ctrl` + `Shift` + 鼠标滚轮：放大/缩小
- 底部栏中的分辨率按钮：打开分辨率输入对话框

### 切换条目/采样

- 鼠标滚轮滚动：转到上一个/下一个条目
- `Up`/`Down`：转到上一个/下一个条目
- 底部栏中的 `<`/`>` 按钮：转到上一个/下一个条目
- `Ctrl` + 鼠标滚轮滚动：转到上一个/下一个采样
- `Ctrl` + `Up`/`Down`：转到上一个/下一个采样
- 底部栏中的 `<<`/`>>` 按钮：转到上一个/下一个采样
- `Ctrl` + `G` 或底部栏中的条目编号按钮：显示 `跳转到条目...` 对话框

### 设置条目备注

- `J` 或条目标题栏中的添加标签按钮：开始编辑条目的标签
- `K` 或点击条目标题栏中的星标按钮：切换条目的星标状态
- `L` 或点击条目标题栏中的完成按钮：切换条目的完成状态

#### 关于备注的设置

您可以在 `设置` -> `偏好设置` -> `编辑器` -> `备注` 中设置隐藏您不需要使用的备注内容。

### 编辑后的操作

您可以更改 `设置` -> `偏好设置` -> `编辑器` -> `编辑后的操作`，以在编辑条目后自动执行以下操作：

- 转到下一个条目
- 将编辑后的条目设置为 `完成`（默认启用）

### 快速启动批量编辑插件

- `F1`~`F8`：启动对应的批量编辑插件。在使用前需要在 `工具` -> `批量编辑` -> `槽位设置...` 中进行配置。
  关于插件，请参阅 [插件](#插件) 了解更多信息。

## 多条目编辑模式

对于采用连续模式的标注器（[例](#处理音频分割标注文件)），你可以在单条目编辑模式和多条目编辑模式间切换。
在多条目编辑模式下，同一采样文件中的互相连接的条目将会被全部显示在屏幕上。您不需切换条目就可以编辑它们。

连续模式的编辑器默认启用多条目编辑模式。您可以点击底部栏中央的 `单/多条目编辑` 按钮来切换。

在多条目编辑模式下，条目的名称会显示在编辑器顶端。您可以通过点击它们执行以下操作：

- 点击：重命名条目
- 长按：转到条目

## 音频格式支持

您可以安装 `ffmpeg` 来支持更多的音频格式。您可以从[官方网站](https://ffmpeg.org/download.html)下载它。
您需要在 `设置` -> `偏好设置` -> `图表` -> `音频格式支持` 中配置 `ffmpeg` 可执行文件的路径。

对于 macOS/Linux，您可以将 `ffmpeg` 安装到 `bin` 或系统 PATH 中，以使默认路径 `ffmpeg` 生效。

## 集成视频

您可以将具有相同名称和时长的视频附加到采样文件，并在编辑时观看该视频。
例如：

```
（采样文件夹）
    - 1.wav
    - 1.mp4
    - 2.wav
    - 2.webm
```

**您需要安装 VLC 才能使用此功能。**您可以从[这里](https://www.videolan.org/vlc/index.html)下载该应用。

请注意，即使在 Apple Silicon mac 上，如果您使用的是从此仓库的 `Release` 页面下载的应用程序，您也需要安装 `macOS`
版本，而不是 `macOS (AppleSilicon)` 版本。

使用快捷键 `V` 或 `Shift` + `V` 在左下角或新窗口中打开附加的视频。视频将静音地与采样文件一起播放。

## 浏览条目

有两个组件显示条目列表：

1. 固定条目列表：默认显示在编辑器右侧。您可以在菜单 `视图` -> `固定条目列表` 中显示或隐藏它。它提供了一个拥有完整功能的条目筛选器（下述）。
2. `跳转到条目...` 对话框：当您按下 `Ctrl` + `G` 或单击底部栏中的条目编号按钮时显示。 它提供了一个简单的条目筛选器。

### 搜索和筛选

在这两种类型的条目列表中，您都可以使用以下格式来搜索条目：

```
aaa;name:bbb;sample:ccc;tag:ddd
```

多个条件通过`;`组合。只有符合所有条件的条目才会被显示。

高级搜索支持以下条件名（`:` 的左边部分）：

- 无条件名：在条目名、采样名（不含扩展名）或标签中搜索
- `name`：在条目名中搜索
- `sample`：在采样名（不含扩展名）中搜索
- `tag`：在标签中搜索

这里的搜索的采用 `包含` 匹配。

在固定条目列表中，您可以单击 `展开` 按钮以显示更多选项。

对于 `完成` 筛选器和 `星标` 筛选器，单击按钮将依次按以下顺序切换：`不筛选`、`仅显示已星标/已完成` 和 `仅显示未星标/未完成`
之间切换。

所有筛选条件将以 `AND` 逻辑结合。

你可以单击 `更多` 按钮来打开一个对话框来使用高级筛选器功能。

### 将筛选器链接到编辑器

默认情况下，项目导航（通过键盘快捷键、鼠标滚轮滚动或按钮单击转到下一个采样/条目等）不受筛选器影响。

例如，即使你已经筛选掉了条目列表中的条目 `no.5`，在显示条目 `4` 时，如果您按下 `Down` 键，仍然将转到条目 `5`。

扩展筛选器中的 `链接` 按钮可以帮助您专注于编辑一组特定的条目。当它被按下时，导航时将跳过固定条目列表中未显示的条目。

在上面的例子中，如果 `链接` 按钮处于按下状态，您将转到条目 `6` 而不是 条目 `5`。

请注意，`跳转到条目...` 对话框不受筛选器的影响，因此您可以通过它转到任何条目，而无需更改或清除固定条目列表中的筛选器设置。

## 工具

您可以使用 `编辑` -> `工具` 下的菜单项来切换工具，或勾选菜单 `视图` -> `显示工具箱` 来显示工具箱。

### 光标

用于拖动参数控制器的普通光标工具。

### 剪刀

在单击位置将条目切割成两个条目。 在[多条目编辑模式](#多条目编辑模式) 中，通常使用这个工具来创建新的标记。

默认情况下，当您使用剪刀单击有效位置时，将会：

1. 播放切割后的第一个条目的音频，方便您确认音素
2. 显示一个输入框来重命名前一个条目
3. 您可以按 `Enter` 来确认输入，或按 `Esc` 来取消
4. 如果您将光标移离单击位置，输入也会被确认
5. 进行切割。第一个条目使用您的输入作为其名称，第二个条目使用原始名称
6. 编辑器转到切割后的第一个条目

在单条目编辑模式下，名称输入将在对话框中请求，而不是在编辑器中。

您可以在 `偏好设置` -> `编辑器` -> `剪刀` 中自定义这些行为。

### 平移

即 `手` 工具。在屏幕上拖动以滚动画布。

### 播放

使用鼠标单击或拖动播放当前采样文件的某个范围。
默认情况下，该工具的操作如下。您可以在 `设置` -> `偏好设置` -> `键位映射` -> `鼠标点击操作` 中更改这些操作的键位绑定。

- 左键单击：从单击位置播放音频，直到音频结束
- 右键单击：从单击位置播放音频，直到屏幕的右端
- `Shift` + 左键单击：从音频起始位置播放，直到单击位置
- `Shift` + 右键单击：从屏幕左端的位置播放，直到单击位置
- `Ctrl` + 左键单击 & 拖动：播放拖动范围内的音频
- `Ctrl` + `Shift` + 左键单击 & 拖动：循环播放拖动范围内的音频

## 标注器

标注器（labeler）是 `vLabeler` 的一种配置文件，它定义了所有针对特定语音合成系统的行为。

例如，内建的 `UTAU oto 标注器` 是一个用于编辑 UTAU 的 `oto.ini` 文件的标注器。

一个标注器包含以下定义：

- 语音条目应包含哪些数据/字段（例如，对于 UTAU，一个条目需要 `固定`、`先行发声`、`重叠` 等）
- 数据/字段显示在编辑器中时的外观
- 条目之间是否连续（指任何条目的开始都应等于其前一个条目的结束）
- 如何将标注文件解析为 `vLabeler` 项目
- 如何从 `vLabeler` 项目生成标注文件
- 如何在 `vLabeler` 项目下构建子项目
- 其他编辑特定类型标注文件时的行为

一些标注器还提供了一些可以在 GUI 中更改的设置项目，而无需编辑标注器配置文件本身。
您可以点击 `新建项目` 页面的 `标注器` 选择框右边的 `齿轮` 按钮来打开标注器设置对话框。

如果你想编辑一个 `vLabeler` 暂不支持的语音合成软件的标注文件，您可以自己编写一个标注器配置文件来实现它，而无需等待我们的开发（尽管需要一定的编程知识）。
请查看 [Develop Custom Labelers](../docs/labeler-development.md) （英文）来了解如何开发一个标注器。

您可以在 `设置` -> `标注器...` 中导入自己的标注器。您也可以将自己编写的标注器分发给其他用户，或联系我们将其内置。

## 插件

目前，您可以使用以下两种类型的插件。

### 模板生成器

模板生成器可以通过输入的文件和参数来生成项目模板。

虽然标注器本身支持生成项目模板，但这样生成的模板只是满足了标注器的最低要求，不方便实际使用。
而模板生成器插件则可以创建复杂的模板。 它们通常还支持一些可定制的参数。

您可以在 `新建项目` 页面上选择所有支持所选标注器的模板生成器。

您可以在 `设置` -> `模板生成器...` 中导入/删除/禁用模板生成器。

### 批量编辑插件

批量编辑插件可用于执行复杂的批量编辑任务。

您可以在 `工具` -> `批量编辑` 中找到可用的批量编辑插件。某些显示的插件可能无法点击，这代表它不支持当前使用的标注器。

您可以在 `工具` -> `批量编辑` -> `管理插件...` 中导入/删除/禁用批量编辑插件。

### 使用脚本

vLabeler 允许您使用自定义脚本来自动化标注任务。

请参阅 [使用自定义脚本在 vLabeler 中完成您的标注任务](../readme/use_scripts.md) 了解更多信息。

#### 可用的插件（除内建）

- [resampler-test](https://github.com/sdercolin/vlabeler-resampler-test): 播放当前条目的 resampler 输出。与 setParam
  的合成测试（F10）功能相似。
- [oto-timing-test](https://github.com/chexq09/vlabeler-oto-timing-check): 将当前条目的音频与节拍器结合输出，用于检查先行发声的位
  置。与 setParam 的发声位置检查（F8）功能相似。

### 插件开发

我们欢迎您为 vLabeler 开发插件。
您可以在任何地方分发您的插件，或者创建一个 Pull Request 来将其内置在 vLabeler 中。

详情请见 [Develop Plugins for vLabeler](../docs/plugin-development.md)（英文）。

## 日志

您可以通过 `帮助` -> `打开日志目录` 来查看 vLabeler 的日志，用于开发/调试/测试等目的。

当您向我们报告问题时，请附上最近的日志文件。

## 应用使用数据的统计

请参阅 [应用使用数据的统计](tracking.md)。

## 已知问题

1. 目前，`键位映射` -> `鼠标滚轮操作` 中的 `向左/右滚动画布`
   操作无法被修改。如果需要使用触控板进行操作，我们建议您将同页面中的 `上/下一个条目`
   操作的快捷键删除，这样您就可以直接使用触控板对画布进行水平方向的滚动，而不会触发条目的切换。
2. 在 Linux 上，文件选择器可能无法选择空文件夹。请在里面创建一些文件，或者将它的路径复制/粘贴到输入框中
3. 在 Linux 上，自动内存回收可能无法正常工作。您可以使用 `工具` -> `回收内存` 来手动回收内存。
4. 有时窗口会意外冻结。您可以通过调整窗口大小来刷新它。
5. 如果除菜单栏以外的所有文本都不可见，请尝试将环境变量 `SKIKO_RENDER_API` 设置为 `SOFTWARE`。
6. 在某些 Linux 发行版上，文件对话框可能无法正常工作。在这种情况下，您可以在 `设置` -> `偏好设置` -> `其他` 中启用自定义文件对话框。
   请注意，自定义文件对话框的功能可能不如系统文件对话框完整。

### 本地化帮助（代码贡献者以外）

[時雨ゆん](https://twitter.com/Yun_Shigure)