sillsdev / transcriber

Flexible audio-text orality solution

Audio Project Manager

(formerly SIL Transcriber)

This project builds a front end web app and an electron app for desktop use on Windows, Linux, and MacOs. It was bootstrapped with Create React App. Create React App Configuration Override (craco) is used to enable the electron desktop app to access the local computer so the program can run without access to the Internet in remote locations.

Installation

Clone the app, go to the project directory, and execute:

1. nvm use 16 # Currently using node v. 16
2. npm install --legacy-peer-deps # legacy required for font loader
3. npm run stamp # this creates a file with the date to display in the version
4. Get a copy of the env-files-transcriber.zip from a team member and unzip it into the env-config folder (see configuration below)
5. Optionally rebuild the localization string.json file (see below)
6. npm run build (web build)

Visual Studio for (strings.json file)

You can use Visual Studio to build updateLocalization.sln (in the localization folder). This file will process the xliff and xlf files to add the strings.json and the localizaiton reducer and model to the source tree. It requires .NET Framework to execute XSLT 2.0 stylesheets. When you first load it, you need to make sure the nuget dependencies are up to date.

1. get the latest localization strings from crowdin (see below)
2. cd localization\bin\Debug
3. execute updateLocalization.exe

NB. You may want ot download the strings from the crowdin site and unzip the file in the localization folder before executing this command to get all the latest localization strings included.

Running Locally

mkdir ~/.aws
touch ~/.aws/credentials
touch ~/.aws/config

Add your keyset to the .aws/credentials file as follows:

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[transcriber]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Then, paste the following into ~/.aws/config:

[default]
region=us-east-2
output=json

[transcriber]
region=us-east-1
output=json

Configuration

Three files are needed to create dev environment configurations:

• env-config/.env.dev.development.local
• env-config/.env.dev.local
• env-config/.auth0-variables.dev.json

Example env-config/.env.dev.development.local:

REACT_APP_ENDPOINT= (url of app)
REACT_APP_HOST= (url of host api or aws gateway)
REACT_APP_HELP= (url of help online)
REACT_APP_COMMUNITY= (url of site for community discussion)
REACT_APP_FLAT= (url of Scripture flat spreadsheet sample)
REACT_APP_HIERARCHICAL= (url of Scripture hierarchical spreadsheet sample)
REACT_APP_GEN_FLAT= (url of general flat spreadsheet sample)
REACT_APP_GEN_HIERARCHICAL= (url of general hierarchical spreadsheet sample)
REACT_APP_SNAGID=(bugsnag client id)

REACT_APP_OFFLINE_not=true
BROWSER=none
REACT_APP_CALLBACK=http://localhost:3000/callback
REACT_APP_SITE_TITLE=Audio Project Manager DEV

Example env-config/.env.dev.local:

REACT_APP_CALLBACK= (url of app followed by /callback)
REACT_APP_ENDPOINT= (url of app)
REACT_APP_HOST= (url of host api)
REACT_APP_HELP= (url of help online)
REACT_APP_COMMUNITY= (url of site for community discussion)
REACT_APP_FLAT= (url of Scripture flat spreadsheet sample)
REACT_APP_HIERARCHICAL= (url of Scripture hierarchical spreadsheet sample)
REACT_APP_GEN_FLAT= (url of general flat spreadsheet sample)
REACT_APP_GEN_HIERARCHICAL= (url of general hierarchical spreadsheet sample)
REACT_APP_SITE_TITLE= (title for browser tab)
REACT_APP_SNAGID=(bugsnag client id)

Example env-config/auth0-variables.dev.json

{
  "apiIdentifier": "(auth0 api audience)",
  "auth0Domain": "(url of auth0 domain)",
  "desktopId": "(auth0 desktop extension -- native client id)",
  "webClientId": "(auth0 spa client id)"
}

Generate dev configuration files

Having created or obtained the .env.* files listed above, generate the environment-appropriate .env.development.local, .env.local and auth0-variables.json files by executing the following:

• npm run devs

NB. You can use qa or prod in place of dev in the command above depending on which environment you want to test with although localhost is only setup by default on the dev environment as a valid source and callback. If you want to add it to the qa channel or the prod channel, you will need to add it in the auth0 console before using it with npm start

Execute app

• npm start # break points can be set in vscode

NB. From vscode you can launch the debugger with F5. The first time you will need to choose the option. There are options for the web and for the desktop electron. This start mode uses two Chrome extensions: React Developer Tools and Redux DevTools Finally, break points and watching variables can be done in the browser or in the developer tools sources tab.

Deployment

The npm run devs, npm run qas and npm run prods commands configure the app to deploy to dev, qa, or prod respectively. There are separate urls and separate AWS S3 buckets for each of these deployments. .

Electron (Desktop) app

The steps above regarding installation and setting up the environments are also applicable to the Electron (Desktop) app.

Electron Development

Selecting Electron: All from the drop down and clicking the "play" icon in the Visual Studio Code editor will allow you to run the program and stop at breakpoints to check values.

• npm run dev # launches electron in developer mode

NB when the developer panel is open, break points can be set in sources and variable values can be watched.

Creating installer

1. npm run pack
2. npm run dist

The dist command creates a folder in the dist folder with an executable that can be launched directly by clicking on it. it also creates an installer in the dist folder that can be distributed.

creating the Linux .deb package

To get setup to do this on you Linux installations you will need:

• sudo apt install devscripts debhelper autotools-dev libsecret-1-dev

The electron-builder program doesn't include the icon as part of the .deb package. It also doesn't install the help file reader. In order to create a more complete .deb package for Linux, use this command:

• bash src/script/makeDeb.sh 2.0.8.4

where 2.0.8.4 is replaced with the latest version number corresponding to the version in the package.json file. The version number in this command is used in naming the file and must agree with the version in the debian/changes file and in debian/control. The .deb created by this command bundles source and binary into the .deb to create a complete package. The package will still need to be signed and deployed to package.sil.org.

creating the Mac dmg package

Signing worked for an earlier version as described below. Now signing has been disabled and you can have it not sign by using this command:

1. npm run pack
2. npm run dist-mac

This notarization process was used when signing was enabled. The Mac package needed to be notarized. This has been setup using these instructions. Thus the Mac should have a file in the repo root directory .env with this format:

APPLEID=email (registered with Apple as a developer)
APPLEIDPASS=password (generated by Apple following instructions)
# for legacy altool
APPLEIDPROVIDER=SummerInstituteofLinguisticsIncSIL
# for notarytool
APPLEIDTEAM=(10 char signature designator) Get SIL signing key
# setting version of Python
PYTHON_PATH=/usr/local/bin/python
# prevent signing with:
CSC_IDENTITY_AUTO_DISCOVERY=false

Test suite

To execute the tests included with the program, use the standard test suite:

npm test