🎧 Valence SDK for Emotion Detection (JavaScript)

valence-sdk is a Node.js SDK for interacting with the Valence Vibrations Emotion Detection API. It provides full support for uploading discrete and async audio files to retrieve their emotional signatures.

✨ Features

• 🎯 Discrete audio processing - Single API call for short audio files
• 🔄 Async audio processing - Multipart streaming for long audio files
• 🎭 Emotion models - Choose between 4-emotion or 7-emotion detection models
• ⚙️ 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

📦 Installation

npm install valence-sdk

🔧 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_ASYNC_URL=https://async-api-url         # Optional: Async audio endpoint  
VALENCE_LOG_LEVEL=info                          # Optional: debug, info, warn, error

Configuration Validation

import { validateConfig } from 'valence-sdk';

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

🚀 Usage

Discrete Audio (Short Files)

import { ValenceClient } from 'valence-sdk';

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

Async Audio (Long Files)

import { ValenceClient } from 'valence-sdk';

try {
  const client = new ValenceClient();
  
  // Upload the audio file
  const requestId = await client.asynch.upload('long_audio.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 'valence-sdk';

// 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 async uploads (default: 5MB)
• maxRetries (number, optional): Maximum retry attempts for async uploads (default: 3)

Returns: ValenceClient instance with discrete and asynch properties

client.discrete.emotions(filePath, model?)

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

Parameters:

• filePath (string): Path to the audio file
• model (string, optional): "4emotions" or "7emotions" (default: "4emotions")

Returns: Promise<Object> - Emotion prediction results

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

client.asynch.upload(filePath)

Uploads async (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 async 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 prediction results

Throws: Error if requestId is invalid or prediction times out

validateConfig()

Validates the current SDK configuration.

Throws: Error if required configuration is missing or invalid

🧪 Examples

Run the included examples:

# Install dependencies
npm install

# Run discrete audio example
npm run example:discrete

# Run async audio example  
npm run example:async

# 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.3.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 'valence-sdk'

Benefits

• ✅ Perfect 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 Vibrations

📜 License

ISC License © 2025 Valence Vibrations