Skip to main content
Version: 3.3.0

Gender identification

Phonexia gender-identification is a tool for calculating the probability of a male or a female voice appearing in a voiceprint.

Versioning​

We use SemVer for versioning.

Quick reference​

How to use this image​

Getting the image​

You can easily obtain the docker image from docker hub. Just run:

docker pull phonexia/gender-identification:latest

Running the image​

info

The preferred way to deploy microservice to a production environment is to use Helm Chart. See the Helm chart deployment for more information.

Docker​

You can start the microservice and list all the supported options by running:

docker run --rm -it phonexia/gender-identification:latest --help

The output should look like this:

Usage: gender-identification [OPTIONS]

Options:
  -h,--help                   Print this help message and exit
  -m,--model file REQUIRED (Env:PHX_MODEL_PATH)
                              Path to a model file.
  -k,--license_key string REQUIRED (Env:PHX_LICENSE_KEY)
                              License key.
  -a,--listening_address address [[::]]  (Env:PHX_LISTENING_ADDRESS)
                              Address on which the server will be listening. Address '[::]' also accepts IPv4 connections.
  -p,--port number [8080]  (Env:PHX_PORT)
                              Port on which the server will be listening.
  -l,--log_level level:{error,warning,info,debug,trace} [info]  (Env:PHX_LOG_LEVEL)
                              Logging level. Possible values: error, warning, info, debug, trace.
  --keepalive_time_s number:[0, max_int] [60]  (Env:PHX_KEEPALIVE_TIME_S)
                              Time between 2 consecutive keep-alive messages, that are sent if there is no activity from the client. If set to 0, the default gRPC configuration (2hr) will be set (note, that this may get the microservice into unresponsive state).
  --keepalive_timeout_s number:[1, max int] [20]  (Env:PHX_KEEPALIVE_TIMEOUT_S)
                              Time to wait for keep alive acknowledgement until the connection is dropped by the server.

Note that the model and license_key options are required. To obtain the model and license, contact Phonexia.

You can specify the options either via the parameters or environmental variables.

Run the container with the mandatory parameters:

docker run --rm -it -v /opt/phx/models:/models -p 8080:8080 phonexia/gender-identification:latest --model /models/gender_identification-xl-5.0.0.model --license_key ${license-key}

Replace the /opt/phx/models, gender_identification-xl-5.0.0.model and license-key with the corresponding values.

With this command, the container will start, and the microservice will be listening on port 8080 on localhost.

Docker compose​

Create a docker-compose.yml file:

version: '3'
services:
  gender-identification:
    image: phonexia/gender-identification:latest
    environment:
      - PHX_MODEL_PATH=/models/gender_identification-xl-5.0.0.model
      - PHX_LICENSE_KEY=<license-key>
    ports:
      - 8080:8080
    volumes:
      - ./models:/models/

Create a models folder in the same directory as the docker-compose.yml file and place a model file in it. Replace <license-key> with your license key and gender_identification-xl-5.0.0.model with the actual name of a model.

Run a microservice:

$ docker compose up

Microservice communication​

gRPC API​

For communication, our microservices use gRPC, which is a high-performance, open-source Remote Procedure Call (RPC) framework that enables efficient communication between distributed systems using a variety of programming languages. We use an interface definition language to specify a common interface and contracts between components. This is primarily achieved by specifying methods with parameters and return types.

Take a look at our gRPC API documentation. The gender-identification microservice defines a GenderIdentification service with remote procedures called Identify. This procedure accepts an argument (also referred to as "message") called IdentifyRequest, which contains an array of voiceprints. This IdentifyRequest argument is streamed, meaning that it may be received in multiple requests, each containing a part of the voiceprints. Once all requests have been received and processed, the Identify procedure returns a message called IdentifyResponse, which consists of the resulting array of IdentifyResult messages that correspond to each voiceprint on the input. The result has a probability score for both male and female appearing in the voiceprint.

Connecting to microservice​

There are multiple ways how you can communicate with our microservices.

Using generated library​

The most common way how to communicate with the microservices is via a programming language using a generated library.

Python library​

If you use Python as your programming language, you can use our official gRPC Python library.

To install the package using pip, run:

pip install phonexia-grpc

You can then import:

  • Specific libraries for each microservice that provide the message wrappers.
  • stubs for the gRPC clients.
# phx_core contains classes common for multiple microservices like `Voiceprint`.
import phonexia.grpc.common.core_pb2 as phx_core
# gender_identification_pb2 contains `IdentifyRequest` and `IdentifyResponse`.
import phonexia.grpc.technologies.gender_identification.v1.gender_identification_pb2 as gid
# gender_identification_pb2_grpc contains `GenderIdentificationStub` needed to make the requests.
import phonexia.grpc.technologies.gender_identification.v1.gender_identification_pb2_grpc as gid_grpc
Generate library for programming language of your choice​

For the definition of microservice interfaces, we use the standard way of protocol buffers. The services, together with the procedures and messages that they expose, are defined in the so-called proto files.

The proto files can be used to generate client libraries in many programming languages. Take a look at protobuf tutorials for how to get started with generating the library in the languages of your choice using the protoc tool.

You can find the proto files developed by Phonexia in this repository.

Using existing clients​

Phonexia Python client​

The easiest way to get started with testing is to use our simple Python client. To get it, run:

pip install phonexia-gender-identification-client

After the successful installation, run the following command to see the client options:

gender_identification_client --help
grpcurl client​

If you need a simple tool for testing the microservice on cmd line, you can use grpcurl. This tool will serialize and send a body that we define in json to an endpoint that we specify.

The body for grpcurl request should look somewhat like this:

{
  "voiceprints": [
    {
      "content": "${voiceprint_1}"
    },
    {
      "content": "${voiceprint_2}"
    },
    ...
  ]
}

For this we already need to have the voiceprints. If you don't have any, you can obtain some using the Phonexia voiceprint-extraction microservice.

In the request, there may be multiple voiceprints in the voiceprints array.

You can obtain such a request body with the following command.

echo -n '{"voiceprints": [{"content": "'$(cat ${path_to_voiceprint_1})'"}, {"content": "'$(cat ${path_to_voiceprint_2})'"}]}' > ${path_to_body}

Replace path_to_voiceprint_1, path_to_voiceprint_2 and path_to_body with corresponding values.

Now you can make the request. The microservice supports reflection. That means that you don't need to know the API in advance to make a request.

grpcurl -plaintext -use-reflection -d @ localhost:8080 phonexia.grpc.technologies.gender_identification.v1.GenderIdentification/Identify < ${path_to_body}

The grpcurl should automatically serialize the response to this query into JSON including the scores in the matrix.

GUI clients​

If you'd prefer to use a GUI client like Postman or Warthog to test the microservice, take a look at the GUI Client page in our documentation. Note that you will still need to convert the audio into the Base64 format manually as those tools do not support it by default either.