Performs liveness detection on a video.
When we receive a video for liveness detection, we perform a passive liveness detection on a bunch of equidistant sampled frames of the video. A decision is made, when one of the breaking conditions is reached:
FailureToAcquire error.
The VideoLivenessDetection API is defined as a unary RPC:
rpc VideoLivenessDetection (VideoLivenessDetectionRequest) returns (LivenessDetectionResponse);
message VideoLivenessDetectionRequest {
bytes video = 1;
}
message LivenessDetectionResponse {
JobStatus status = 1;
repeated JobError errors = 2;
repeated ImageProperties image_properties = 3;
bool live = 4;
double liveness_score = 5;
}
The VideoLivenessDetectionRequest message has a single field:
videoThis API requires a valid JWT in the Authorization request header and accepts an optional reference number.
| Authorization | Required Bearer authentication. Please refer to BWS API Authentication for a description of how to provide a valid JWT here. |
| Reference-Number | Optional, client specific reference number, which will be added to the BWS bookkeeping as well as to the response header. You typically use this reference to link the resulting BWS bookkeeping entries with your logs. |
On success the API returns a LivenessDetectionResponse message with the fields as follows:
statuserrorsimage_propertieslivetrue, the provided video is supposed to be recorded from a live person. No errors are reported in this case.
When this field is set to false, there is at least one error reported that explains, why the provided video is supposed not to be recorded from a live person.
liveness_scoreAn informative liveness score (a value between 0.0 and 1.0) that reflects the confidence level of the live decision. The higher the score, the more likely the person is a live person. If this score is exactly 0.0, it has not been calculated and an error has been be reported.
In case that the live field is set to false, at least one of the following errors is reported in the errors field:
Beside of the success return status code OK (0), this call might also return one of the following gRPC error status codes to indicate an error:
All successful BWS gRPC calls return a response header and a response trailer containing additional information about the request:
| Response Header | |
| jobid | The Job-ID (a GUID) that has been assigned to this BWS call. |
| bws-version | The version of the BWS gRPC service. |
| reference-number | An optional reference number as provided in the request header. |
| date | The timestamp when the request has been received at the server. |
| ... | Other headers that might have been added by the server (NGINX, Kestrel, ...) that was handling the request. |
| Response Trailer | |
| response-time-ms | The timespan in milliseconds the request spent at the BWS service. |
| ... | Other trailers, like exception trailers, which are added by the gRPC framework in case an RPC exception occurred. |
Here is a short example of how to call into the VideoLivenessDetection gRPC API using a video loaded from a file.
Please refer to BWS API Authentication for a description of the methods CreateAuthenticatedChannel and GenerateToken.
The tooling package Grpc.Tools can be used to generate the C# assets from the bws.proto file.
Refer to overview for gRPC on .NET to learn more about how to call into a gRPC service with a .NET client.
try
{
using GrpcChannel channel = CreateAuthenticatedChannel(new Uri(options.Host), GenerateToken(options.ClientId, options.Key));
var client = new BioIDWebService.BioIDWebServiceClient(channel);
var request = new VideoLivenessDetectionRequest { Video = ByteString.CopyFrom(File.ReadAllBytes(options.File)) };
var call = client.VideoLivenessDetectionAsync(request);
LivenessDetectionResponse response = await call.ResponseAsync.ConfigureAwait(false);
// ...
Console.WriteLine($"This was live: {response.Live} (confidence: {response.LivenessScore:F2})");
}
catch (RpcException ex)
{
Console.Error.WriteLine($"gRPC error from calling service: {ex.Status.StatusCode} - '{ex.Status.Detail}'");
}
To generate Java classes from a bws.proto file use the Protobuf compiler (protoc) with the command in cmd or in terminal : protoc --java_out=OUTPUT_DIR bws.proto
For gRPC client stubs, add the gRPC plugin and use the command: protoc --java_out=OUTPUT_DIR --grpc-java_out=OUTPUT_DIR --plugin=protoc-gen-grpc-java=PATH_TO_PLUGIN bws.proto
For a detailed step by step guide on protobuf usage with Java, please refer to Java detailed guide
import java.util.concurrent.CompletableFuture;
import com.bioid.services.BioIDWebServiceGrpc;
import com.bioid.services.BioIDWebServiceGrpc.BioIDWebServiceStub;
import com.bioid.services.Bws.LivenessDetectionResponse;
import com.bioid.services.Bws.VideoLivenessDetectionRequest;
import com.google.protobuf.ByteString;
import io.grpc.ManagedChannel;
import io.grpc.StatusRuntimeException;
import io.grpc.stub.StreamObserver;
public void videoLivenessDetectionAsync( byte[] video)
{
try
{
String jwtToken = generateToken(options.clientId, option.secretKey, options.expireMinutes);
ManagedChannel channel = createAuthenticatedChannel(option.host, jwtToken);
BioIDWebServiceStub bwsClientAsync = BioIDWebServiceGrpc.newStub(channel);
VideoLivenessDetectionRequest videoRequest = VideoLivenessDetectionRequest.newBuilder()
.setVideo(ByteString.copyFrom(video))
.build();
CompletableFuture <LivenessDetectionResponse> videoLivenessResult=new CompletableFuture <>();
bwsClientAsync.videoLivenessDetection(videoRequest, new StreamObserver <LivenessDetectionResponse>() {
@Override
public void onNext(LivenessDetectionResponse value)
{
videoLivenessResult.complete(value);
}
@Override
public void onError(Throwable t)
{
videoLivenessResult.completeExceptionally(t);
}
@Override
public void onCompleted()
{
}
});
LivenessDetectionResponse videoLivenessDetecionResponse = videoLivenessResult.get();
System.out.printf("This was live: %s - Confidence: %f", videoLivenessDetecionResponse.getLive(), videoLivenessDetecionResponse.getLivenessScore());
} catch (StatusRuntimeException ex)
{
System.err.printf("gRPC error from calling service: %s - '%s'", ex.getStatus(), ex.getStatus().getDescription());
} catch (Exception ex)
{
System.err.printf("Error processing images: " + ex.getMessage());
}
}
Using the protocol buffer compiler protoc (install: python -m pip install grpcio-tools)
from the Phython gRPC tools
you can create the Phyton client code from the .proto service definition:
python -m grpc_tools.protoc --proto_path=. --python_out=. --grpc_python_out=. bws.proto
import grpc
import bws_pb2_grpc
import bws_pb2
token = GenerateToken(args.clientid, args.key, 10)
with CreateAuthenticatedChannel(args.host, token) as channel:
stub = bws_pb2_grpc.BioIDWebServiceStub(channel)
request = bws_pb2.VideoLivenessDetectionRequest()
with open(args.file, 'rb') as f:
request.video = f.read()
try:
response = stub.VideoLivenessDetection(request)
except grpc.RpcError as rpc_error:
print("Received error: ", rpc_error)
print response