Package com.javiergs.cortex4j

Class CortexClient

java.lang.Object
com.javiergs.cortex4j.CortexClient
All Implemented Interfaces:
AutoCloseable
public final class CortexClient extends Object implements AutoCloseable
Main entry point for reading EMOTIV Cortex headset streams.

Connect with your registered application credentials, add a CortexListener, and subscribe to a stream. This class manages authorization, headset selection, and the underlying network connection. The first available headset is selected automatically.

For a first experiment, run EMOTIV Launcher, connect a headset (or Virtual Brainwear), and create a cortex4j.properties file on the classpath containing cortex.client.id and cortex.client.secret. Alternatively, set the CORTEX_CLIENT_ID and CORTEX_CLIENT_SECRET environment variables. 


 try (CortexClient cortex = CortexClient.connect()) {
   cortex.addListener("met", sample ->
       System.out.println(sample.getValues()));
   cortex.subscribe("met");
   Thread.sleep(30_000);
 }

Supported streams and their availability depend on the headset, Cortex permissions, and EMOTIV licensing. Use try-with-resources to close the active session when finished.

See Also:

  • Method Details

    • connect

      public static CortexClient connect()
      Connects to the local Cortex service and opens an authenticated headset session.
      Returns:
      connected client; close it when finished
      Throws:
      IllegalStateException - if credentials, headset, authorization, or connection fail

    • connect

      public static CortexClient connect(CortexCredentials credentials)
      Connects using credentials for a registered Cortex application.
      Parameters:
      credentials - application client ID and secret
      Returns:
      connected client
      Throws:
      NullPointerException - if credentials is null
      IllegalStateException - if authorization or connection fails

    • connectAsync

      public static CompletableFuture<CortexClient> connectAsync(CortexCredentials credentials)
      Opens an authenticated session without blocking the caller.
      Parameters:
      credentials - registered application credentials
      Returns:
      future completing with a connected client, or exceptionally on failure

    • connectAsync

      public static CompletableFuture<CortexClient> connectAsync(URI endpoint, CortexCredentials credentials)
      Opens an authenticated session at a specified Cortex WebSocket endpoint.
      Parameters:
      endpoint - Cortex WebSocket URI
      credentials - registered application credentials
      Returns:
      future completing with a connected client, or exceptionally on failure

    • addListener

      public void addListener(String stream, CortexListener listener)
      Registers an observer for a stream such as dev, met, eeg, mot, or pow. Register before subscribing.
      Parameters:
      stream - Cortex stream name
      listener - callback invoked for each matching sample
      Throws:
      IllegalArgumentException - if stream is blank
      NullPointerException - if listener is null

    • removeListener

      public void removeListener(String stream, CortexListener listener)
      Unregisters a stream observer; this does not unsubscribe the stream.
      Parameters:
      stream - Cortex stream name
      listener - previously registered callback

    • subscribe

      public void subscribe(String... streams)
      Subscribes to one or more Cortex data streams.

      Available streams depend on headset and account entitlements.

      Parameters:
      streams - one or more stream names, such as "dev" or "met"
      Throws:
      IllegalArgumentException - if no streams are provided
      IllegalStateException - if the subscription is rejected or the client is closed

    • unsubscribe

      public void unsubscribe(String... streams)
      Unsubscribes from one or more Cortex streams.
      Parameters:
      streams - one or more stream names to stop
      Throws:
      IllegalArgumentException - if no streams are provided
      IllegalStateException - if the client is closed or the request fails

    • getHeadsetId

      public String getHeadsetId()
      Returns the identifier of the headset selected during connection.
      Returns:
      selected headset ID

    • getSensorLabels

      public List<String> getSensorLabels()
      Returns sensor labels reported for the selected headset.

      Labels may be empty; do not assume a fixed channel layout.

      Returns:
      immutable list of sensor labels

    • getConnectionSecurity

      public ConnectionSecurity getConnectionSecurity()
      Returns the security mode of the established WebSocket connection.
      Returns:
      connection security mode

    • close

      public void close()
      Closes the active Cortex session and releases its network connection.

      Safe to call more than once.

      Specified by:
      close in interface AutoCloseable