Installation Guide¶

Overview¶

This guide provides detailed instructions for installing Audex from DEB packages on Debian-based Linux distributions.

This project is distributed as DEB packages for AMD64 and ARM64 architectures.

System Requirements¶

Supported Architectures¶

• amd64 (x86_64)
• arm64 (aarch64)

Supported Operating Systems¶

• Debian 11 (Bullseye) or later
• Ubuntu 20.04 LTS or later
• Raspberry Pi OS (64-bit)

Required Privileges¶

Audex runs as a normal user (not root). Installation requires root privileges, but runtime operations are executed as your regular user account.

Installation¶

Step 1: Download DEB Package¶

Download the appropriate DEB package for your system architecture from the GitHub Releases page.

ARM64:

wget https://github.com/6ixGODD/audex/releases/download/v{version}/audex_{version}_arm64.deb

AMD64:

wget https://github.com/6ixGODD/audex/releases/download/v{version}/audex_{version}_amd64.deb

Step 2: Install Package¶

Install the downloaded package using dpkg:

sudo dpkg -i audex_{version}_arm64.deb

If dependency errors occur during installation, run:

sudo apt-get install -f

Step 3: Installation Process¶

The installation process performs the following operations:

1. Create System Directories
2. /opt/audex/ - Application installation directory
3. /etc/audex/templates/ - Configuration templates

4. /etc/audex/systemd/ - User systemd service template

5. Setup Python Virtual Environment

6. Creates Python virtual environment at /opt/audex/venv

7. Install Audex from PyPI

8. Downloads and installs Audex package and dependencies from Python Package Index

9. Generate Configuration Templates

10. /etc/audex/templates/config.system.yml - System default configuration template

11. /etc/audex/templates/config.example.yml - Configuration reference example

12. Prepare User Directories

13. Creates directory structure for existing users:

    • ~/.config/audex/ - User configuration
    • ~/.local/share/audex/store/ - Audio file storage
    • ~/.local/share/audex/logs/ - Application log files

14. Update Desktop Integration

15. Installs desktop entry at /usr/share/applications/audex.desktop
16. Installs application icon
17. Updates desktop database and icon cache

Step 4: Verify Installation¶

Verify the installation was successful:

# Check installed package version
dpkg -l | grep audex

# Verify executable files
which audex
which audex-setup
which audex-enable-service

# Check desktop file
ls -la /usr/share/applications/audex.desktop

# Check icon
ls -la /usr/share/pixmaps/audex.svg

Expected output:

/usr/bin/audex
/usr/bin/audex-setup
/usr/bin/audex-enable-service

Inspect installed directory structure:

# Configuration templates
ls -la /etc/audex/templates/

# Service template
ls -la /etc/audex/systemd/

# Installation directory
ls -la /opt/audex/

Configuration¶

Initial Setup Wizard¶

After installation, run the interactive setup wizard to configure Audex (as your normal user, not root):

audex-setup

The setup wizard guides you through the following steps:

1. Check Existing Configuration

2. If configuration exists, offers options to edit or overwrite

3. Load Configuration Template

4. Reads default configuration from /etc/audex/templates/config.system.yml

5. Expands environment variables (e.g., ${HOME})

6. Audio Device Detection

7. Detects available input devices on your system

8. Configure Transcription Provider

9. Prompts for Dashscope API Key

10. Configure VPR Provider

11. Prompts for XFYun App ID, API Key, API Secret

12. Save Configuration

13. Writes configuration to ~/.config/audex/config.yml

14. Initialize VPR Group (Optional)

15. Creates voice print recognition group
16. Group ID is saved to ~/.config/audex/.xf.vprgroup

Configuration Files¶

Manual Configuration¶

Manually edit your configuration file:

nano ~/.config/audex/config.yml

Refer to /etc/audex/templates/config.example.yml for all available configuration options.

Running Audex¶

From Application Menu¶

After installation, Audex appears in your application menu under AudioVideo > Audex.

Manual Execution¶

Start Audex manually from command line:

audex

To stop the application, press Ctrl+C or close the window.

User Systemd Service (Recommended for Auto-Start)¶

Enable Auto-Start Service¶

To enable Audex to start automatically on boot:

audex-enable-service

This command: - Installs user systemd service from template - Enables the service for your user - Enables linger for boot persistence - Starts the service immediately

Manual Service Management¶

If you prefer to manage the service manually:

# Start service
systemctl --user start audex.service

# Stop service
systemctl --user stop audex.service

# Restart service
systemctl --user restart audex.service

# Enable auto-start
systemctl --user enable audex.service
sudo loginctl enable-linger $USER

# Disable auto-start
systemctl --user disable audex.service
sudo loginctl disable-linger $USER

# Check service status
systemctl --user status audex.service

Viewing Logs¶

User Systemd Logs¶

View real-time service logs:

journalctl --user -u audex.service -f

View recent logs:

journalctl --user -u audex.service -n 100

Application Log Files¶

View real-time application logs:

tail -f ~/.local/share/audex/logs/audex.log

View recent logs:

tail -n 50 ~/.local/share/audex/logs/audex.log

Search for errors in logs:

grep -i error ~/.local/share/audex/logs/audex.log

System and User Directories¶

System Directories¶

User Directories¶

Uninstallation¶

Remove Package (Preserve User Data)¶

Remove Audex but keep user configuration and data:

# Disable service first (if enabled)
systemctl --user stop audex.service
systemctl --user disable audex.service
sudo loginctl disable-linger $USER

# Remove package
sudo apt-get remove audex

Preserved user directories: - ~/.config/audex/ - ~/.local/share/audex/

Complete Removal (Purge)¶

Remove Audex and all system files:

# Disable service first (if enabled)
systemctl --user stop audex.service
systemctl --user disable audex.service
sudo loginctl disable-linger $USER

# Purge package
sudo apt-get purge audex

# Manually remove user data (optional)
rm -rf ~/.config/audex
rm -rf ~/.local/share/audex
rm -rf ~/.config/systemd/user/audex.service

安装指南¶

概述¶

本指南提供在基于 Debian 的 Linux 发行版上从 DEB 包安装 Audex 的详细说明。

本项目基于 DEB 分发,适用于 AMD64 和 ARM64 架构。

系统要求¶

支持的架构¶

• amd64 (x86_64)
• arm64 (aarch64)

支持的操作系统¶

• Debian 11 (Bullseye) 或更高版本
• Ubuntu 20.04 LTS 或更高版本
• Raspberry Pi OS (64 位)

所需权限¶

Audex 以**普通用户**身份运行（非 root）。安装需要 root 权限，但运行时操作以常规用户帐户执行。

安装步骤¶

步骤 1：下载 DEB 包¶

从 GitHub Releases 页面下载适合您系统架构的 DEB 包。

ARM64：

wget https://github.com/6ixGODD/audex/releases/download/v{version}/audex_{version}_arm64.deb

AMD64：

wget https://github.com/6ixGODD/audex/releases/download/v{version}/audex_{version}_amd64.deb

步骤 2：安装软件包¶

使用 dpkg 安装下载的软件包：

sudo dpkg -i audex_{version}_arm64.deb

如果安装过程中出现依赖错误，运行：

sudo apt-get install -f

步骤 3：安装过程¶

安装过程将执行以下操作：

1. 创建系统目录
2. /opt/audex/ - 应用程序安装目录
3. /etc/audex/templates/ - 配置模板

4. /etc/audex/systemd/ - 用户 systemd 服务模板

5. 设置 Python 虚拟环境

6. 在 /opt/audex/venv 创建 Python 虚拟环境

7. 从 PyPI 安装 Audex

8. 从 Python Package Index 下载并安装 Audex 包及其依赖项

9. 生成配置模板

10. /etc/audex/templates/config.system.yml - 系统默认配置模板

11. /etc/audex/templates/config.example.yml - 配置参考示例

12. 准备用户目录

13. 为现有用户创建目录结构：

    • ~/.config/audex/ - 用户配置
    • ~/.local/share/audex/store/ - 音频文件存储
    • ~/.local/share/audex/logs/ - 应用程序日志文件

14. 更新桌面集成

15. 在 /usr/share/applications/audex.desktop 安装桌面条目
16. 安装应用程序图标
17. 更新桌面数据库和图标缓存

步骤 4：验证安装¶

验证安装是否成功：

# 检查已安装的软件包版本
dpkg -l | grep audex

# 验证可执行文件
which audex
which audex-setup
which audex-enable-service

# 检查桌面文件
ls -la /usr/share/applications/audex.desktop

# 检查图标
ls -la /usr/share/pixmaps/audex.svg

预期输出：

/usr/bin/audex
/usr/bin/audex-setup
/usr/bin/audex-enable-service

检查已安装的目录结构：

# 配置模板
ls -la /etc/audex/templates/

# 服务模板
ls -la /etc/audex/systemd/

# 安装目录
ls -la /opt/audex/

配置¶

初始化设置向导¶

安装后，运行交互式设置向导配置 Audex（以普通用户身份，非 root）：

audex-setup

设置向导将引导您完成以下步骤：

1. 检查现有配置

2. 如果配置存在，提供编辑或覆盖选项

3. 加载配置模板

4. 从 /etc/audex/templates/config.system.yml 读取默认配置

5. 展开环境变量（例如 ${HOME}）

6. 音频设备检测

7. 检测系统上可用的输入设备

8. 配置转录服务提供商

9. 提示输入 Dashscope API Key

10. 配置声纹识别提供商

11. 提示输入 XFYun App ID、API Key、API Secret

12. 保存配置

13. 将配置写入 ~/.config/audex/config.yml

14. 初始化 VPR 组（可选）

15. 创建声纹识别组
16. 组 ID 保存到 ~/.config/audex/.xf.vprgroup

配置文件¶

手动配置¶

手动编辑您的配置文件：

nano ~/.config/audex/config.yml

参考 /etc/audex/templates/config.example.yml 获取所有可用的配置选项。

运行 Audex¶

从应用程序菜单¶

安装后，Audex 出现在应用程序菜单的 音频视频 > Audex 下。

手动执行¶

从命令行手动启动 Audex：

audex

停止应用程序，按 Ctrl+C 或关闭窗口。

用户 Systemd 服务（推荐用于自动启动）¶

启用自动启动服务¶

要启用 Audex 在开机时自动启动：

audex-enable-service

此命令： - 从模板安装用户 systemd 服务 - 为您的用户启用服务 - 启用 linger 以实现开机持久性 - 立即启动服务

手动服务管理¶

如果您希望手动管理服务：

# 启动服务
systemctl --user start audex.service

# 停止服务
systemctl --user stop audex.service

# 重启服务
systemctl --user restart audex.service

# 启用自动启动
systemctl --user enable audex.service
sudo loginctl enable-linger $USER

# 禁用自动启动
systemctl --user disable audex.service
sudo loginctl disable-linger $USER

# 检查服务状态
systemctl --user status audex.service

查看日志¶

用户 Systemd 日志¶

查看实时服务日志：

journalctl --user -u audex.service -f

查看最近的日志：

journalctl --user -u audex.service -n 100

应用程序日志文件¶

查看实时应用程序日志：

tail -f ~/.local/share/audex/logs/audex.log

查看最近的日志：

tail -n 50 ~/.local/share/audex/logs/audex.log

搜索错误日志：

grep -i error ~/.local/share/audex/logs/audex.log

系统和用户目录¶

系统目录¶

用户目录¶

卸载¶

移除软件包（保留用户数据）¶

移除 Audex 但保留用户配置和数据：

# 首先禁用服务（如果已启用）
systemctl --user stop audex.service
systemctl --user disable audex.service
sudo loginctl disable-linger $USER

# 移除软件包
sudo apt-get remove audex

保留的用户目录： - ~/.config/audex/ - ~/.local/share/audex/

完全移除（清除）¶

移除 Audex 及所有系统文件：

# 首先禁用服务（如果已启用）
systemctl --user stop audex.service
systemctl --user disable audex.service
sudo loginctl disable-linger $USER

# 清除软件包
sudo apt-get purge audex

# 手动删除用户数据（可选）
rm -rf ~/.config/audex
rm -rf ~/.local/share/audex
rm -rf ~/.config/systemd/user/audex.service