Deployment Manual (for Linux)

1. System and Software Requirements

Please check whether the relevant items meet the requirements before deployment.

Please use a root account or execute all the following commands with sudo privileges from a non-root account.

2. Resource Package

3. File Structure

4. Quick Start Guide

Please use the root account, or execute all the following commands with sudo privileges from a non-root account.

4.1. Run Environment Check

Unzip the environment check file, taking the amd64 (x86_64) architecture as an example:

tar xzvf check_env_linux_amd64.tar.gz

Navigate into the unzipped directory and run ./check_env.sh. If all items show pass, it means the hardware environment supports the system operation. If there is an error, it means the hardware environment does not meet the conditions for system operation.

After completion, press the Enter key to exit the environment check.

4.2. Install Speech-to-Text Main Program

Obtain the compressed file: asr-integrated.zip.

1. After unzipping, you will get the main program directory asr-integrated. For example, if you unzip it to the /work/ directory:

unzip asr-integrated.zip -d /work/

2. Navigate to the main program directory and run the installation program install.run:

cd /work/asr-integrated
./install.run

3. Follow the installation wizard for setup. First, select the edition to install by entering the corresponding number and pressing Enter. If you are unsure, please confirm with the pre-sales team which edition is suitable for you.

   Option	Function
   Pro Edition	Short Speech Transcription, Real-time Speech Transcription, Audio File Transcription
   Premium Edition	Short Speech Transcription, Real-time Speech Transcription
   File Edition	Audio File Transcription
   Cancel	Exit the installation program

   After confirming the installation edition again, enter Y to begin the installation; otherwise, enter any other character to exit the installation wizard.

   Please enter your choice: (1~4)
   1) Pro Edition
   2) Premium Edition
   3) File Edition
   4) Cancel
   #? 1【※This is provided as an example only; please contact the pre-sales team to confirm the edition that is suitable for your needs.】
   Please comfirm to install Pro Edition (Y/N):y

4. The display of Installation completed. indicates that the main program has been successfully installed. The next step is to install the model; please follow the deployment documentation for further actions.

4.3. Install Speech-to-Text Model

The model comes in two packaging forms, ISO and ZIP (based on what the pre-sales team provides), and the installation methods differ.

4.3.1. Installation Package in ISO Format

If the downloaded file is an ISO format image file (e.g., asr-model_ja-JP.iso), proceed as follows:

1. Confirm the location where the image will be mounted, such as /mnt, or create an empty directory using the mkdir command.

2. Load the image file into the specified location in loop mode:

   mount -o loop asr-model_ja-JP_Linux.iso /mnt

   The prompt mounted read-only indicates that the loading is complete.

3. Create a symbolic link to the model directory under the main program

   ln -s /mnt/* /work/asr-integrated/model/

4. Navigate to the model directory and run the model installation program install.run

   cd /work/asr-integrated/model
   ./install.run

5. Follow the installation wizard to install, which will automatically detect the installed version of the main program. Enter Y to confirm the installation version.

   Pro Edition is detected.
   Please confirm to install ja-JP model for Pro Edition (Y/N):Y

6. The display of Installation completed. indicates that the model installation is complete.

7. Execute umount /mnt to remove the image mount. After unmounting, you can move or delete the .iso image file.

4.3.2. ZIP Format Compression Package

If the downloaded file is a ZIP format compressed file (e.g., asr_ja-JP.zip), then:

Unzip the file into the model directory under the main program:

unzip -o asr_ja-JP.zip -d /work/asr-integrated/model/

If there are multiple model compressed files, repeat the above steps, ensuring all are unzipped to the corresponding path.

4.4. Launch for the First Time

Navigate to the main program directory asr-integrated and run the program using the script ./script/start.sh.

4.4.1. Activation via Command Line

Upon the first launch, the system will display the following message, indicating that activation is required. Please follow the on-screen prompts to copy the content shown on the screen and send it to the sales staff to obtain an authorization code. Do not exit the program during this process.

Tip:

If it is not convenient to copy the machine code from the command line, you can refer to the "4.4.2. Activation via Web Page" section for alternative steps.

[root@server asr-integrated]# ./script/start.sh
Loading ASR model ...
Please send the following content to the pre-sales team:
M90C5iimJUBg9QhmrPtK+AiSLUt85dtJbet787/D9Mo6qCiMgjR0rTvaBWVjroeKxgHrOdr...
Please enter the authorization code: 
▋

Paste the received authorization code into the command line window. Then press the Enter key to proceed to the next step.

Note:

Copy: Selecting the text with the mouse will automatically copy it; no further action is needed. Paste: Right-click the mouse, or press the Shift + Insert(Ins) shortcut key.

DO NOT use other shortcuts to copy the machine code or paste the authorization code, as it may cause the program to exit, leading to the invalidation of the machine code/authorization code.

After waiting for a few seconds, the following content will be displayed, indicating that the model has been loaded successfully and the Speech Recognition (ASR) and/or Audio File Transcription (ASR-FILE) services have been correctly started. The screen will show the port where the services are running, which defaults to 7100.

[root@server asr-integrated]# ./script/start.sh
Loading ASR model ...
Loading ja-JP model... [OK]
ASR model was loaded successfully.
Loading ASR-FILE model ...
Loading ja-JP model... [OK]
ASR-FILE model was loaded successfully.
Loading VAD model ...
VAD model was loaded successfully.
ASR module was launched successfully, listening on http://localhost:7100 and ws://localhost:7100
ASR-FILE module was launched successfully, listening on http://localhost:7100

If an error is prompted after entering the authorization code, it indicates that the activation has failed. In this case, please rerun the ./script/start.sh to perform the activation again.

Note:

After the activation is completed, the activation information will be saved on this machine. Do not change the hardware, as it may cause the activation to become invalid.

4.4.2. Web Activation

Keep the start.sh process running. If it is not running, navigate to the main program directory asr-integrated/ and launch the program with ./script/start.sh.

Enter server_ip:port/admin in the browser on the local machine or another machine within the LAN, such as 192.168.1.2:7100/admin, to open the admin panel.

Click the Generate button, copy the machine code (or scan the QR code on the right), and send it to the pre-sales team to obtain an authorization code. During this period, do not regenerate the machine code, as doing so will invalidate the previously generated machine code.

After receiving the authorization code, copy and paste it into the text box below, then click the Confirm button to complete the activation. After activation via the web page, you will need to manually restart the Speech-to-Text service.

4.5. Shutting Down the Program

To stop the Speech-to-Text program, you can simply press Ctrl + C to exit the program.

4.6. Restarting

Run the program again by executing ./script/start.sh. Wait for the screen to display a success message, indicating that it is ready for normal use.

5. Advanced Operations

Please execute all the following commands with the root account, or with sudo privileges from a non-root account.

5.1. Command Arguments

Format: ./script/start.sh [option]

5.2. Starting the Service in the Background

The following two methods have slightly different supported features. Please choose one according to your needs.

5.2.1 Simple Method

Running the command ./script/start.sh -d can achieve a simple background start and process daemon.

To stop the service running in the background, please run the command ./script/stop.sh.

5.2.2. Registration as a System Service

Register the program as a system service using a script, using the systemd component to achieve advanced features such as auto-start on boot, run in the background, process daemon, and log management.

1. Run the ./script/systemd.run script (which depends on the systemd component).
2. Follow the prompts to make a selection. After entering the option and pressing Enter, input Y to confirm and execute.

Example:

Please enter your choice: (1~3)
1) Register System Service    3) Cancel
2) Unregister System Service
#? 1
Please comfirm to Register System Service (Y/N):y
Register system service successfully.

Note:

If systemd is not installed on the Linux server, you can install it using commands like yum install systemd or apt install systemd. After installing systemd, run the ./script/systemd.run script.

1. After registering as a system service, you can use the systemctl command to control the speech recognition service.

   # To start the service
   systemctl start asr
   # To stop the service
   systemctl stop asr
   # To restart the service
   systemctl restart asr
   # To check the status of the service
   systemctl status asr
   # To disable auto-start on boot
   systemctl disable asr
   # To enable auto-start on boot
   systemctl enable asr
   # To view real-time logs
   journalctl -fu asr

5.3. Modifying the Service Port

The default service port is 7100. If you need to change it, please open the service.toml file in the installation directory with a text editor and modify the port number after port = on the second line, for example: port = 8888.

After saving and exiting, restart the service for the changes to take effect.

5.4. Service Management API

5.4.1. Authorization Management Related API

5.4.1.1. Generating Machine Code

Request Line

GET /auth/machine_code

Response Parameters

5.4.1.2. Input Authorization Code

Request Line

POST /auth/auth_code

Request Parameters (JSON)

Response Parameters

5.4.1.3. Query Authorization Status

Request Line

GET /auth/auth_status

Response Parameters

5.4.1.4. Export License Backup File

Only permanent license can be exported as a backup file; non-permanent license can be only exported as a demo file for debugging interface purposes, which do not contain authorization information and cannot be used for actual use.

Request Line

GET /auth/license

Response Parameters

License backup file license.dat

5.4.1.5. Import Authorization Backup File

Only permanent license backup files are supported for import; demo files exported from a non-permanent license can be only imported for debugging interface purposes, which do not contain authorization information and cannot be used for actual use.

Request Line

POST /auth/license

Request Parameters (form-data)

Return Parameters

5.4.2. Information Inquiry Related API

5.4.2.1. Query System Version

Request Line

GET /version

Response Parameters

Components include:

5.4.2.2. Query Real-time Speech Recognition and Short Speech Transcription Connection Status

Also used to check connectivity.

Request Line

GET /asr

Response Parameters

5.4.2.3. Query Audio File Transcription Connection Status

Also used to check connectivity.

Request Line

GET /asr-file

Response Parameters

5.5. Moving or Copying the Software to Another Device

1. Package the asr-integrated directory and copy it to the target device, then extract it to a suitable location.

Tip:

The audio and log folders contain audio and log files, which may occupy a large amount of space. Depending on the situation, you may choose not to copy them to the target device.

2. On the target device, execute ./script/start.sh --remove-license, otherwise, an error might occur.
3. Follow the section 4.4. Launch for the First Time to complete the activation.
4. Note: If the voiceprint component (module_vpr) has been installed, you need to unbind the license on the old server and reinstall and bind on the new server.

5.6. Optional Functional Components

5.6.1. Voiceprint Component (For Speaker Diarization)

Docker version 18.09 or higher must be installed in advance.

Install the Dongle Driver

Please use the command service senseshield status or systemctl status senseshield to check if the driver has already been installed. If the response is senseshield.service not found or a similar message, please refer to the Dongle User Manual to complete the driver installation. If not, it indicates that the driver has already been installed; please skip the installation steps and proceed directly to activation.

Activation

Voiceprint components require a standalone license. Depending on whether the server can connect to the internet, there are two activation methods. You can choose either one:

• Online Binding

  In an online environment, enter the following command in the terminal, and then proceed with the "Confirm Activation Status" steps below.

  ssclt --online_bind_license_key --license_key xxxx-xxxx-xxxx-xxxx (the authorization code provided by the pre-sales)

• Offline Binding

  In an offline environment, you can use offline binding for activation.

  Run the following command on the offline server to generate hardware fingerprint file:

  ssclt --offline_bind_c2d --c2d ./

  A file with a suffix of ".c2d" will be generated in the current directory, for example: PC_192.168.0.54.c2d

  Copy the generated C2D file to any other computer that has internet access. Log in to https://user.lm.virbox.com/sn/login.html on the computer and enter the authorization code provided by the pre-sales.

  In the "Offline Binding" section , use the generated C2D file to get a D2C update file. The file name will be like PC_192.168.0.54.D2C.

  Copy the D2C file back to the offline server and run the following command:

  ssclt --update_d2c --d2c ./PC_192.168.0.54.D2C

  Then proceed with the "Confirm Activation Status" steps below.

Confirm Activation Status

You can list the license information using the following command:

ssclt -l

The LicenseId in the returned results represents the existing license ID. To use the voiceprint component, there must be a license ID 813000 on the server.

Import Docker Image

Unzip the module_vpr_{version}.zip file provided by the pre-sales team into the main program directory, making sure to replace /work/asr-integrated with the actual working path.

unzip -o module_vpr_1.0.4.zip -d /work/asr-integrated/
docker import module/module_vpr_1.0.4.tar module_vpr:1.0.4

Run a Docker Container

docker run -itd --name=module_vpr --shm-size=2g -p 7810:7810  \
--restart=always --privileged -v /tmp:/tmp \
module_vpr:1.0.4 /bin/bash -c "cd /home/module_vpr/ && ./run.sh"

Check the Status of the Container

docker logs -f module_vpr

The appearance of the following message indicates that the startup was successful:

[INFO]: vad model is loaded.
[INFO]: emb model is loaded.
[INFO]: cluster model is loaded.

6. FAQ

It says Please install ASR System first! when I was installing the model.

1. The main program is not installed. Please refer to "4.2. Install Speech-to-Text Main Program" to complete the installation.

2. Confirm the location of the model installation files, which should be in the model directory under the main program directory.

No Response to a Request

1. Please check if the service is running properly by executing the ps -ef|grep asr-integrated command to see if there is a corresponding process.
2. Please check the firewall settings to allow the port for the TCP protocol (default is 7100).

How to Configure HTTPS/WSS Connections

The Speech-to-Text service only provides HTTP/WS interfaces. You can configure SSL certificates through Nginx and set up a reverse proxy for the original interfaces to implement HTTPS/WSS interfaces.

Reference for Nginx configuration file:

server {
    listen       443 ssl;
    server_name   mydomain.com;   #Nginx Server's Domain Name
    ssl_certificate     /etc/nginx/ssl/nginx.cer; # Certificate Path
    ssl_certificate_key  /etc/nginx/ssl/nginx.key; # Private Key Path

    location /asr/ {                  
        proxy_pass http://127.0.0.1:7100/;   #Speech-to-Text service
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

After the configuration above is effective, you can:

• Use wss://mydomain.com/asr/ws/v1 as the endpoint for Real-time Speech Transcription and Short Speech Transcription services.
• Use https://mydomain.com/asr/request as the endpoint for creating Audio File Transcription tasks.
• Use https://mydomain.com/asr/version as the endpoint for checking the version number.
• Other APIs follow the same pattern.

Installation of Voiceprint Component Failed During Activation (Binding)

If you encounter the error code 0x22001001, please execute the following command:

wget https://download.virbox.com/virboxtools/hwss/senseshield-2.5.0.60698-x86_64.sh
chmod +x senseshield-2.5.0.60698-x86_64.sh
./senseshield-2.5.0.60698-x86_64.sh install

Then retry activation (binding).