Skip to content

Manual client installation on macOS

Preparing the package

  1. Download A.V.A.T.A.R client zip file from GitHub.
    • Click on the code button and Download zip.
  2. Extract the A.V.A.T.A.R-Client-master.zip file using "Extract or Extract here" selection.
  3. In your Desktop, create a Desktop/packager/client directory which will be used to package the application.

  4. Copy the contents of Downloadsd/A.V.A.T.A.R-Client-master/dist to Desktop/packager/client.

    $ cd Downloads/A.V.A.T.A.R-Client-master/dist
$ cp - r * $HOME/Desktop/packager/client

Installing the packager module

  1. Open a terminal
  2. Change to ./Desktop/packager/client_ directory: 
    cd ./Desktop/packager/client

  3. Enter the following command to install the packager and all application modules: 

    client % npm install --save-dev @electron/packager

    About deprecated modules

    You can ignore messages about deprecated modules.
    These messages are not important and the installation can continue.

  4. After a few moments, you should see the following result: 

    added <xxx> packages, and audited <xxx> packages in 19s

<xx> packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

    Check vulnerabilities!

    The application is updated regularly, but it is possible that you may discover vulnerabilities (the 'found 0 vulnerabilities' can be more than 0).
    If this is the case, installation is unaffected and can continue.
    You can also contribute by leaving an issue to update the application.

Running the packager module

In order to have the latest version of Electron for your installation, you need to retrieve the latest version from the Electron GitHub which will be used to package it.

  1. Go to the Electron GitHub web site and on the right, in the Releases section, below the About section, note the latest version (as in the example image below, framed in red):

  2. Run the packager:

    • Suppose that the lastest version readed on the Electron site is 34.8.1, then change the XX.X.X value to the latest version in the --electron-version=XX.X.X parameter in the command line below then execute it.

    ``` client % npx electron-packager . --electron-version=XX.X.X --icon=./avatar.ico --out=output ````

  3. After a few moments, you should see the following result (varies by platform): 

    Packaging app for platform win32 x64 using electron vXX.X.X (the latest version from Electron GitHub site)
Wrote new app to: output\A.V.A.T.A.R-Client-darwin-x64

    Warning

    The architecture name depends of the packaging, it can be A.V.A.T.A.R-Client-darwin-x64 or A.V.A.T.A.R-Client-darwin-arm64.

    In the section below, we assume that it is A.V.A.T.A.R-Client-darwin-x64 but it can be A.V.A.T.A.R-Client-darwin-arm64. If it is the case, change the directory name according to your platform.

Installing Electron module

  1. Change to the output/A.V.A.T.A.R-Client-darwin-x64/A.V.A.T.A.R-Client.app/Contents/Resources/app directory:

    client % cd ./output/A.V.A.T.A.R-Client-darwin-x64/A.V.A.T.A.R-Client.app/Contents/Resources/app

  2. Enter the following command to install Electron in the package: 

    app % npm install electron --save-dev

  3. After a few moments, you should see the following result: 
    added <xxx> packages, changed <x> packages, and audited <xxx> packages in 13s

<xx> packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities

Deploy A.V.A.T.A.R client as an application

A.V.A.T.A.R client is now ready to be moved into its application directory.

You have two possible choices:

  1. Copy (or move) the contents of the Desktop/packager/client/output/A.V.A.T.A.R-client-darwin-x64 directory to a Desktop directory and start the client with the A.V.A.T.A.R-Client.app icon.
  2. Create an A.V.A.T.A.R-Client application.

Choose what you want to do below (between « Move to a Desktop directory » or « Create an application »)

  1. Open a Finder and change to Desktop/packager/client/output/A.V.A.T.A.R-Client-darwin-x64 directory.
  2. Select the A.V.A.T.A.R-Client icon and drop it to the Applications section (to the left of the Finder)
  1. Create a directory for the A.V.A.T.A.R client (e.g. Desktop/avatar/client).

  2. Copy (or move) the contents of the Desktop/packager/client/output/A.V.A.T.A.R-Client-darwin-x64 directory to Desktop/avatar/client. 

    cd /Users/<account>/Desktop/packager/client/output/A.V.A.T.A.R-Client-darwin-x64
mv -r * /Users/<account>/Desktop/avatar/client

    note: You can use a Finder to do the same thing.

installing Sox

A client needs Sox to register intercoms with other clients.

  1. If Homebrew is not already installed, install it first.

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Install Sox using Homebrew:

    % brew install sox

installing FFmpeg

A client needs ffplay to play sound and music files.

  1. Install FFmpeg using Homebrew:

    % brew install ffmpeg

HTTPS certificate

The client's speech recognition uses the Web Speech API interface, which can be accessed by all browsers. As a result, a client embades a version of Google Chrome when it is installed to ensure perfect compatibility with the client's version at all times.

To ensure secure communication between Google Chrome and the client, you need to create an HTTPS certificate.
Follow the first step first, then return to this page to complete the client installation:

  1. Create a self-signed certificate.

  2. Importing the Certificate Authority to the keystore:

    1. Open a terminal
    2. Change to Desktop/packager/certificates/CA directory

    3. Enter the following command to import the Certificate Authority in the keystore

      sudo security add-trusted-cert -d -k /Library/Keychains/System.keychain "./avatarCA.crt"

    4. Enter your user password

      • if needed, enter your user password to unlock the keystore

  3. Depending on whether you have chosen “Move to a desktop directory” or “Create an application” for your installation, select the following steps in the tab below:

  1. Create a certificates directory for the host certificate:
    1. Open a Finder
    2. Change to "Applications"
    3. Select the A.V.A.T.A.R-Client app
    4. Right click and select "Display package contents"
    5. Change to the Contents/Resources/app/core/chrome directory
    6. Create a certificates directory
    7. Change to certificates directory
  2. Copy the host certificate to the certificates directory:
    1. Open a new Finder
    2. Change to Desktop/packager/client/certificates/hote
    3. Select and copy <server name\>.crt and <server name\>.key files to the certificates directory created in the previous step
  1. Create a certificates directory for the host certificate:
    1. Open a Finder
    2. Change to the Desktop/avatar/client directory
    3. Select the A.V.A.T.A.R-Client app
    4. Right click and select "Display package contents"
    5. Change to the Contents/Resources/app/core/chrome directory
    6. Create a certificates directory
    7. Change to certificates directory
  2. Copy the host certificate to the certificates directory:
    1. Open a new Finder
    2. Change to Desktop/packager/client/certificates/hote
    3. Select and copy <server name\>.crt and <server name\>.key files to the certificates directory created in the previous step

Checking Certificate Authority installation

After the installation you can check the import of the certificate authority in the keystore.

  1. Open a Finder

  2. Search for "Utility" -> "Keychain access"

  3. Open "Keychain access"

  4. In the menu, select "System"

  5. Search for "A.V.A.T.A.R client CA" certificate

  6. You should see "This certificate is marked as trusted for all users"

Adding IP adress to the hosts file

A macOS installation needs the IP adress and the hostname added in the /etc/hosts

  1. Open the System settings and change to Network
  2. Click to Ethernet and see the IP adress field
    • For example, you could see a IP adress like 192.168.2.25
    • Remember the IP adress
  3. Open a terminal

  4. Enter the following command to get the hostname

    scutil --get LocalHostName
// Remember the hostname

  5. Enter the following line to edit the /etc/hosts file

    sudo vi /etc/hosts

  6. Enter your password to modify the file

  7. In the editor, go to to last line of the file by the arrow down key
  8. Press the ALT-A keys
  9. Press the Enter key 2 times

  10. Add the IP adress and the hostname:

    • For example, suppose that the IP adress is 192.168.2.25 and the hostname is avatar then the line will be:
    192.168.2.25  avatar

    As this example, add YOUR IPadress and YOUR hostname

  11. Press the ESC key

  12. Save the file and quit by the following line:

    :wq!

  13. If you want, you can check if the file is modified by:

    more /etc/hosts

Voices

A.V.A.T.A.R needs voices to dialog with you. There are two possibilities for selecting voices according to their availability:

  1. In the system language packs (Local voices)
  2. In Chrome speech synthesis (Remote voices)
Platform System voices Google Chrome
remote voices		 Comment
macOS ok ok No action required.
System and Chrome voices are available.

Start the client

Warning

Start the A.V.A.T.A.R server first!

Start the client according to the installation choice.

Type Action
macOS application 1. Open a Finder and click on the A.V.A.T.A.R Client application
In a directory 1. Open a Finder and change to the Desktop/avatar/client.
2. Double-click on the A.V.A.T.A.R-Client app directory
For a shortcut, Options->Keep in dock
Warning

Warning: if you have anti-virus software, it may notify you that the application does not have a valid digital signature. Click on "always authorize".

The first connection window appears:

Add required information

  1. Enter the information required to start the client:
    • The client name.
    • The server's UDP search range:
      • You can enter a search range in the format XXX.XXX.XXX.XXX-XXX
        • For example:
          • with 192.168.2.100-110, the client will look for the server at addresses 192.168.2.100 to 110
        • You can also enter the server address directly, for example: 192.168.2.100
    • The UDP search port:
      • By default: 3333
      • This port number must be identical to the one defined in the server properties.
      • If you haven't changed it on the server, leave the default port.
  2. Click on "Save"
  3. The client restarts

Add the host certificate

  1. The client window displays a warning message telling you that HTTPS has not been configured by an orange message:

  2. Left-click on the client's name to open its context menu.

    Warning

    Always wait until the client is fully initialized before clicking on its name to open its context menu.
    Wait until you see the the The HTTPS certificate is missing... message in the console.

  3. Click on Edit -> Plugin Studio:

  4. In Plugin Studio, click on the Plugins tab, then click on the Chrome plugin.

  5. Click on the Properties tab:

    • Add the <server name>.key file name to the key property (see HTTPS certificates for more details).
    • Add the <server name>.crt file name to the cert property (see HTTPS certificates for more details).
    • Add the server name to the address property.
    • Uncheck the headless property to display Chrome on next startup and check if the certificate is valid.
    Tip

    In the image, a “sb-portable” is placed in the fields.

    This is just an example!

    You should see the name of your <server name>.crt and <server name>.key files (located in the app/core/chrome/certificates directory)

  6. Right-click and click Save to save the properties

  7. Close the window (using the cross)
  8. Restart the client

Checking the host certificate

After restarting the client, Chrome appears.
Verify if the HTTPS certificate is valid in the Chrome browser.

Expected result (the sb-portable hostname is only a example, you must see the hostname of your platform):

Warning

If your certificate is not valid, maybe the certificate has not been made correctly.
Repeat the certificate creation step.

If the certificate is valid, open Plugin Studio again and change the headless property to true to hide Chrome the next time it is started. Do not forget to save the properties:

Tip

Chrome properties are defined in a chrome plugin so that they can be easily modified from within Plugin Studio.

Never delete this plugin, or the client will stop working!

You can now set some mandatory parameters at client startup.

Mandatory parameters

You're starting the client for the first time.
Although some client properties have been configured automatically, others need to be changed quickly.

  1. Do a right click here and select 'Open link in new tab' to display the Client Settings page access.

  2. Then, change these parameters to complet the installation:

    • Dialog language - Mandatory -
      • Defines the language used for voice rules.
      • By default the language is seted to "English".
      • You have to define the language you want and associated voice parameters (voice preference and current voice).

    • Trigger keywords - Optional/Mandatory -

      • Defines trigger keywords to start listening.
      • The default keywords are "Sarah" and "Jarvis".
      Warning

      Depending on the language you've chosen, the Trigger keywords may not be understood.
      If you've changed the dialog language, you'll need to change the trigger keyword.

    • Rules - Optional/Mandatory -

      • Defines phrases that are used by you or by the client when replying to you.
      • At the installation, these parameters are set in "English" language.
      • If you've changed the dialog language, you'll need to change the rules.
    • Application language - Optional -
      • Defines the language used for all graphical interfaces and application messages.
      • At the installation, this parameter is set to "English" (you can choose between "English or "French").
      • If "English" is the language you need, you can bypass this step.
    • The background image - Optional -
      • A Background image for the client. Not mandatory but so much nicer!

Test the installation

You can now test the installation by downloading your first plugin.



Server installation Test the installation