¶ BSocial FAQ
This page answers common questions about the BSocial SDK, covering both general-purpose (social robotics, kiosks, mobile) and automotive in-cabin deployments. For full detail see the BSocial SDK User Guide and the Technical Application Guide.
Note: This FAQ was drafted from the existing BSocial and BAutomotive user guides plus the BSocial Technical Application Guide. Please review the answers against current licensing and support policy before publishing, as some details (e.g. exact SLAs, pricing, contract terms) are not covered in the source documents and have been left as placeholders.
¶ Table of Contents
- General
- Licensing
- Platforms & System Requirements
- Camera, Image & Audio Requirements
- Installation & Getting Started
- Features & Outputs
- Automotive Deployments
- Privacy & Data
- Troubleshooting & Support
¶ General
¶ What is BSocial?
BSocial is Blueskeye AI's software development kit (SDK) for automatic behaviour data processing and analysis. It tracks faces, gaze, head pose and facial expressions in real time, and derives behavioural and emotional signals such as valence, arousal, dominance, emotion zones, expressed mood, engagement and (in automotive deployments) drowsiness. It is designed to run entirely on-device (at the edge), without needing to send data to the cloud.
¶ What can BSocial be used for?
BSocial can be used in social robots and virtual assistants, customer experience and kiosk applications, mobile apps, and in-vehicle driver/occupant monitoring systems. It is designed to be deployed either standalone (via its command line tool) or embedded into another product via its C++, C, Python or Unity C# APIs.
¶ Does this FAQ cover BAutomotive too?
Yes. BSocial and the automotive-focused BAutomotive SDK have been combined into a single product. Older documentation or SDK packages you may have referring to "BAutomotive" cover the same underlying technology; automotive-specific features (drowsiness detection, cough/sneeze detection, CAN bus output, in-vehicle camera placement guidance) are called out with an (Automotive) tag throughout the User Guide.
¶ How many people can BSocial track at once?
Up to 5 people at a time. This limit can be lowered via the set_max_faces_to_track API method if you only need to track fewer people.
¶ Does BSocial require an internet connection?
No. BSocial performs all input processing and analysis locally on the host device. An internet connection is only needed if your licence key uses online licence verification (see Licensing).
¶ Licensing
¶ Do I need a licence key to use BSocial?
Yes. BSocial will not operate without a valid licence key. Keys are issued per client and may be scoped to a specific time period and/or a specific set of enabled features.
¶ What's the difference between online and offline licence verification?
Online keys verify against a remote Blueskeye licence server at SDK initialisation and require an internet connection. Offline keys are tied to a specific machine (see --print-machine-id) and don't require connectivity. Which type you receive depends on your contractual agreement with Blueskeye; by default, evaluation and standard licences are issued as online keys.
¶ How do I pass a licence key into the SDK?
Either as a .bskai licence file (load_licence_key) or as a raw string (set_licence_key). Note that load_licence_key may not be available in security-hardened builds of the SDK.
¶ What is the difference between the Standard and Advanced output levels?
Standard is the default tier and covers the core face, gaze, affect, emotion, image quality and (where applicable) automotive signals. Advanced adds full 15-point Action Unit output and raw Gaze Origin data, and is reserved for trusted partners who need granular facial muscle movement data. See SDK Output Levels for the full breakdown.
¶ My licence doesn't include a feature I requested in code — what happens?
If you request a CSV section or output that isn't included in your licence's output level, the SDK omits it and prints a warning to the console rather than failing outright.
¶ Platforms & System Requirements
¶ Which platforms does BSocial support?
linux-x64, linux-arm64, darwin-x64 (Intel Mac), darwin-arm64 (Apple Silicon), windows-x64, ios-arm64 and android-arm64-v8a. See System Requirements for minimum OS versions per platform.
¶ Which Python versions are supported?
Python 3.7–3.12 on most platforms. On darwin-arm64 and linux-arm64, support starts at Python 3.8 (3.7 is not supported on those two platforms).
¶ Are all features available on every platform?
Mostly, but macOS and Windows builds are primarily intended for evaluation/demo purposes and may lack some functionality present in the Linux builds. CAN bus support (automotive) is not currently available on macOS.
¶ Does BSocial need any extra system packages to run?
On Linux, the command line tool (not the SDK library itself) requires LIBGTK-3.0 to be installed system-wide.
¶ Camera, Image & Audio Requirements
¶ What image formats does BSocial accept?
8-bit unsigned integer images in BGR, RGB, BGRA, RGBA or MONOCHROME format, in either standard colour or near-infrared (NIR).
¶ What's the minimum face size BSocial needs to work reliably?
At least 256x256 pixels for the face region; the SDK enforces a minimum tracked-face diagonal of 141 pixels and will reject faces below that after detection. Smaller faces than the recommended 256x256 will see reduced output quality.
¶ What audio format does BSocial expect?
44100 Hz sample rate, single (mono) channel, signed 16-bit integer samples. No other sample rate or channel count is currently accepted.
¶ Where should I place the camera for best results?
Frontal placement relative to the face gives the best performance, though BSocial is tolerant of yaw/pitch variation. For in-vehicle deployments, see Camera Placement in Vehicles and the Hardware Requirements appendix of the Technical Application Guide for supported mounting positions and recommended camera specifications.
¶ Installation & Getting Started
¶ How do I install BSocial?
There's no formal installer — download the zip archive matching your target platform, unpack it anywhere on disk, and reference that location (<SDK_PACKAGE_PATH>) from your code or the command line tool. See Installation.
¶ How do I check my installation is working?
Run the bundled BM.BSocial-tests executable from the bin folder with your licence key: ./BM.BSocial-tests -l <LICENCE_KEY_PATH>. A successful run prints a summary of passed tests. See Post-Installation Tests.
¶ Can I use BSocial without writing any code?
Yes — the bundled command line tool BM.BSocial-app can analyse video files, audio files or live camera/microphone feeds, optionally visualising results and writing predictions to CSV, with no additional software required. See Command Line Tool Usage.
¶ Which languages have an API?
C++, C, Python and Unity C#. Full worked examples are provided for Python and C++ in the User Guide.
¶ Features & Outputs
¶ What does BSocial output for each frame?
Depending on configuration: face ID/re-identification, face bounding box, 68 facial landmarks (with visibility flags), 3D head pose and position, gaze angle/vector, up to 15 Action Units, Valence/Arousal/Dominance affect scores, an overall ImHO confidence score, image quality flags, emotion zone classification, and voice activity detection — plus attention/gaze-to-object mapping, confusion and interaction engagement scores where enabled. See API Outputs Reference for the full structure definitions.
¶ What is the ImHO score?
A single overall confidence score (0–1) combining a Visibility score and a Frontal Pose score, indicating how reliable the SDK's predictions are likely to be for a given frame.
¶ What is "Expressed Mood" and how is it different from the per-frame emotion outputs?
Most BSocial outputs are per-frame. Expressed Mood instead aggregates behaviour over a longer window (10 seconds to 5 minutes) into a single continuous score from -1.0 to +1.0, representing longer-term affective state rather than momentary expression.
¶ Can I re-identify the same person across multiple sessions?
Yes, via the persistent face enrolment functions (add_neutral_face and related methods), either through the command line tool or the API. This is off by default and is not intended to be used as an authentication mechanism.
¶ Can I get the raw CSV output instead of using the API directly?
Yes — pass an output path to the command line tool or call set_output_path() / start_write() / stop_write() via the API. You can control exactly which column groups are written using a BMCSVConfig object. See Output CSV Format.
¶ Automotive Deployments
¶ What extra capabilities does BSocial offer for in-vehicle use?
Drowsiness estimation, cough/sneeze detection, additional in-cabin camera placement guidance, and the ability to publish predictions directly onto a vehicle's CAN bus for consumption by other onboard systems.
¶ How do I send BSocial predictions over CAN bus?
Call init_canbus() once the API is initialised (specifying the target CAN device, e.g. vcan0), then use send_canbus_message() to publish data packets. This capability is not currently available on macOS builds.
¶ Where should the camera be mounted in a vehicle?
Supported placements include the driver A-pillar, passenger A-pillar, rear-view mirror, and dashboard centre or direct-facing positions, covering both left-hand-drive and right-hand-drive vehicles. See Camera Placement in Vehicles.
¶ Privacy & Data
¶ Does BSocial send video, audio or personal data to Blueskeye or the cloud?
No. All input processing and behavioural analysis happens locally on the host device. The only network dependency is licence verification, and only for licence keys configured for online verification — no video, audio or derived behavioural data is transmitted as part of that check.
¶ Is the re-identification feature a form of facial recognition / authentication?
It identifies that the same previously-seen face has returned (for continuity of behavioural tracking), but it is explicitly not designed or intended to be used as an authentication or identity-verification mechanism.
¶ Troubleshooting & Support
¶ The Python module fails to import — what should I check first?
Confirm you're running a supported Python version for your platform (python --version) and that you've added the SDK's python folder to sys.path before importing. On some systems, python still points at Python 2 — try python3 instead.
¶ My CSV is missing a column I expected — why?
Either that data group isn't enabled by default (most are opt-in via BMCSVConfig — see Output CSV Format), or it's restricted by your licence's output level, in which case the SDK omits it and logs a warning instead of failing.
¶ Who do I contact for support?
help@blueskeye.com, or your Blueskeye account contact. For licensing, feature-availability or contractual questions, contact your Blueskeye representative directly, as these are not fully covered by the SDK documentation.
¶ Company / legal details
AI system provider: Blueskeye Ltd (company registration number 11953581). Headquarters: The Ingenuity Centre, University of Nottingham Innovation Park, Triumph Road, Nottingham, NG7 2TU, UK.