@h-ear/core

Shared API client for the H-ear World audio classification API. Used by @h-ear/mcp-server and @h-ear/openclaw.

Install

npm install @h-ear/core

Usage

import { HearApiClient, resolveConfigFromEnv } from '@h-ear/core';

const config = resolveConfigFromEnv(); // reads HEAR_API_KEY + HEAR_ENV
const client = new HearApiClient(config);

const result = await client.classifyUrl({ url: 'https://example.com/audio.mp3' });

GPS Location

const result = await client.classify({
    url: 'https://example.com/audio.mp3',
    latitude: -33.8688,
    longitude: 151.2093,
});
// result.location → { latitude: -33.8688, longitude: 151.2093 }

Both latitude and longitude must be provided together. The server applies a GPS priority cascade: file-embedded > client-provided > IP geolocation. JobResult.location is returned when coordinates are available.

Authentication

Two auth modes — HearApiClient picks the right header automatically:

| Mode | Header sent | When used | |------|------------|-----------| | API Key | X-NCM-Api-Key: ncm_sk_... | stdio transport (Claude Desktop, OpenClaw) | | Bearer token | Authorization: Bearer <JWT> | OAuth 2.1 + PKCE via APIM (Streamable HTTP) |

resolveConfigFromEnv() reads HEAR_API_KEY. Bearer tokens are passed via ServerConfig.bearerToken — obtained automatically by Claude Desktop/Code via RFC 9728 OAuth discovery.

Two tools (healthCheck, listClasses) need no auth.

Config

import { resolveConfigFromEnv, type ServerConfig } from '@h-ear/core';

// From env vars
const config = resolveConfigFromEnv();

// Manual
const config: ServerConfig = {
    apiKey: 'ncm_sk_your_key',
    environment: 'prod',
    baseUrl: 'https://api.h-ear.world',
    apiPath: '/api',
};

| Variable | Description | Default | |----------|-------------|---------| | HEAR_API_KEY | H-ear Enterprise API key | (required for classify tools) | | HEAR_ENV | Target environment (dev, staging, prod) | prod | | HEAR_BASE_URL | Override base URL | Environment default |

Environments

| Env | Base URL | |-----|----------| | prod | https://api.h-ear.world | | staging | https://api-staging.h-ear.world | | dev | https://api-dev.h-ear.world |

Exports

| Export | Description | |--------|-------------| | HearApiClient | HTTP client — all API operations | | HearApiError | Typed error with status, code, requestId | | resolveConfigFromEnv() | Build ServerConfig from environment variables | | apiUrl(config, path) | Resolve full URL for a given API path | | ENVIRONMENTS | Base URL map per environment | | HEAR_API | API constants (formats, limits, noop callback URL) | | getAudioDuration(filePath) | Audio duration detection via ffprobe (returns 0 when unavailable) |

Requirements

• Node.js >= 18
• ffprobe (optional — duration detection for upload routing)

License

MIT