Valence SDK for Emotion Detection

valenceai is a Node.js SDK for interacting with the Valence AI Pulse API for emotion detection. It provides a convenient interface to upload audio files -— short or long —- and retrieve detected emotional states.

Features

• Discrete audio processing - Single API call for short audio files
• Asynch audio processing - Multipart streaming for long audio files
• Environment configuration - Built-in support for .env configuration
• Enhanced logging - Configurable log levels with timestamps
• Robust error handling - Comprehensive validation and error recovery
• TypeScript ready - Full JSDoc documentation for all functions
• 100% tested - Comprehensive test suite with 95%+ coverage
• Security focused - Input validation and secure error handling

The emotional classification model used in our APIs is optimized for North American English conversational data.

The API includes a baseline model of 4 basic emotions. The emotions included by default are angry, happy, neutral, and sad. Our other model offerings include different subsets of the following emotions: happy, sad, angry, neutral, surprised, disgusted, nervous, irritated, excited, sleepy. 

Coming soon – The API will include a model choice parameter, allowing users to choose between models of 4, 5, and 7 emotions.

The number of emotions, emotional buckets, and language support can be customized. If you are interested in a custom model, please contact us.

API Functionality

While our APIs include the same model offerings in the backend, they are best suited for different purposes.

| | DiscreteAPI | AsynchAPI | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Inputs | A short audio file, 4-10s in length. | A long audio file, at least 5s in length. Inputs can be up to 1 GB large. | | Outputs | A JSON that includes the primary emotion detected in the file, along with its confidence. The confidence scores of all other emotions in the model are also returned. | A time-stamped JSON that includes the classified emotion and its confidence at a rate of 1 classification per 5 seconds of audio. | | Response Time | 100-500 ms | Dependent upon file size |

The DiscreteAPI is built for real-time analysis of emotions in audio data. Small snippets of audio are sent to the API to receive feedback in real-time of what emotions are detected based on tone of voice. This API operates on an approximate per-sentence basis, and audio must be cut to the appropriate size.

The AsynchAPI is built for emotion analysis of pre-recorded audio files. Files of any length, up to 1 GB in size, can be sent to the API to receive a summary of emotions throughout the file. Similar to the DiscreteAPI, this API operates on an approximate per-sentence basis, but the AsyncAPI provides timestamps to show the change in emotions over time.

Coming soon – StreamingAPI via WebSockets for real-time analysis of an audio stream.

Installation

npm install valenceai

Configuration

Create a .env file in your project root:

VALENCE_API_KEY=your_api_key                    # Required: Your Valence API key
VALENCE_DISCRETE_URL=https://discrete-api-url   # Optional: Discrete audio endpoint
VALENCE_ASYNCH_URL=https://asynch-api-url        # Optional: Asynch audio endpoint  
VALENCE_LOG_LEVEL=info                          # Optional: debug, info, warn, error

Configuration Validation

import { validateConfig } from 'valenceai';

try {
  validateConfig();
  console.log('Configuration is valid!');
} catch (error) {
  console.error('Configuration error:', error.message);
}

Usage

Discrete Audio (Short Files)

import { ValenceClient } from 'valenceai';

try {
  const client = new ValenceClient();
  const result = await client.discrete.emotions('YOUR_FILE.wav');
  console.log('Emotion detected:', result);
} catch (error) {
  console.error('Error:', error.message);
}

Asynch Audio (Long Files)

import { ValenceClient } from 'valenceai';

try {
  const client = new ValenceClient();
  
  // Upload the audio file
  const requestId = await client.asynch.upload('YOUR_FILE.wav');
  console.log('Upload complete. Request ID:', requestId);
  
  // Get emotions from uploaded audio
  const emotions = await client.asynch.emotions(requestId);
  console.log('Emotions detected:', emotions);
} catch (error) {
  console.error('Error:', error.message);
}

Advanced Usage

import { ValenceClient } from 'valenceai';

// Custom client configuration
const client = new ValenceClient(
  2 * 1024 * 1024,  // 2MB parts
  5                 // 5 retry attempts
);

// Upload with custom configuration
const requestId = await client.asynch.upload('huge_file.wav');

// Custom polling with more attempts and shorter intervals
const emotions = await client.asynch.emotions(
  requestId,
  50,    // 50 polling attempts
  3      // 3 second intervals
);

API Reference

new ValenceClient(partSize?, maxRetries?)

Creates a new Valence client with nested discrete and asynch clients.

Parameters:

• partSize (number, optional): Size of each part in bytes for asynch uploads (default: 5MB)
• maxRetries (number, optional): Maximum retry attempts for asynch uploads (default: 3)

Returns: ValenceClient instance with discrete and asynch properties

client.discrete.emotions(filePath)

Predicts emotions for discrete (short) audio files using a single API call.

Parameters:

• filePath (string): Path to the audio file

Returns: Promise<Object> - Emotion prediction results

Throws: Error if file doesn't exist, API key missing, or request fails

client.asynch.upload(filePath)

Uploads asynch (long) audio files using multipart upload for processing.

Parameters:

• filePath (string): Path to the audio file

Returns: Promise<string> - Request ID for tracking the upload

Throws: Error if file doesn't exist, API key missing, or upload fails

client.asynch.emotions(requestId, maxAttempts?, intervalSeconds?)

Retrieves emotion prediction results for asynch audio processing.

Parameters:

• requestId (string): Request ID from client.asynch.upload
• maxAttempts (number, optional): Maximum polling attempts (default: 20, range: 1-100)
• intervalSeconds (number, optional): Polling interval in seconds (default: 5, range: 1-60)

Returns: Promise<Object> - Emotion detection results

Throws: Error if requestId is invalid or detection times out

validateConfig()

Validates the current SDK configuration.

Throws: Error if required configuration is missing or invalid

Inputs and Outputs

Inputs

The APIs expect mono audio in the .wav format. An ideal audio file is recorded at 44100 Hz (44.1 kHz), though sampling rates as low as 8 kHz can still be used with high accuracy. For custom use cases, microphone specifications can be customized based on audio environment, including optimizations for mono/stereo audio, single microphone applications, noisy environments, etc. 

For the DiscreteAPI, input data is an audio file in the .wav format.

For the AsynchAPI, input data is an audio file in the .wav format.

Outputs

Outputs are returned as JSONs in the following formats: 

DiscreteAPI:

{
  "main_emotion": "happy",
  "confidence": 0.777777777,
  "all_predictions": {
    "angry": 0.123456789,
    "happy": 0.777777777,
    "neutral": 0.23456789,
    "sad": 0.098765432
  }
}

The emotion returned in main_emotion is the highest confidence emotion returned from the model. Within all_predictions, each emotion is followed by its level of confidence. Some may use the top two highest confidence emotions to generate more nuanced states. We recommend dropping a main_emotion with confidence under 0.38, but that is at the user's discretion.

AsynchAPI:

{
  "request_id": "27a33189-bdd7-47ca-9817-abacfb7bdaf4",
  "status": "completed",
  "emotions": [
    {
      "t": "00:00",
      "emotion": "neutral",
      "confidence": 0.82791723
    },
    {
      "t": "00:05",
      "emotion": "neutral",
      "confidence": 0.719817432
    },
    {
      "t": "00:10",
      "emotion": "happy",
      "confidence": 0.917309381
    },
    {
      "t": "00:15",
      "emotion": "neutral",
      "confidence": 0.414097846
    }
	"..."
  ]
}

The emotions returned in emotions are the highest confidence emotion returned from the model, alongside the timestamp and confidence. The number of values in emotions correlates directly to the length of the input file. We recommend dropping emotions with confidence under 0.38, but that is at the user's discretion.

Examples

Run the included examples:

# Install dependencies
npm install

# Run discrete audio example
npm run example:discrete

# Run asynch audio example  
npm run example:asynch

# Or run directly
node examples/uploadShort.js
node examples/uploadLong.js

Development

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Building and Publishing

# Validate configuration and run tests
npm test

# Publish to npm
npm login
npm publish --access public

What's New in v0.5.0

Major Changes

• Unified Client Architecture - Single ValenceClient with nested discrete and asynch clients
• API Restructure: predictDiscreteAudioEmotion() → client.discrete.emotions()
• API Restructure: uploadAsyncAudio() → client.asynch.upload()
• API Restructure: getEmotions() → client.asynch.emotions()
• Single Import: import { ValenceClient } from 'valenceai'

Benefits

• API Symmetry - Identical structure to Python SDK
• Intuitive Organization - Related methods grouped together
• Consistent Naming - Same method names across Python and JavaScript
• Enhanced Documentation - Updated examples and migration guide
• Maintained Quality - All existing functionality preserved

See CHANGELOG.md for complete details and migration guide.

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Ensure all tests pass: npm test
5. Submit a pull request

Support

• Documentation: See API Reference above
• Issues: GitHub Issues
• Questions: Contact Valence AI

License

Private License © 2025 Valence Vibrations, Inc, a Delaware public benefit corporation.