Note HarmonyOS SDK

中文

Upload audio/video to Note and follow processing from native ArkTS apps. Requires HarmonyOS 5.0+ (API 12). An API key can query recordings uploaded with that same key. View transcripts, summaries and playback in Note.

Run this command in your app module:

ohpm install @olares/note-sdk

For a specific published version, use ohpm install @olares/note-sdk@<version>.

Declare network permission in the app module's module.json5:

"requestPermissions": [{ "name": "ohos.permission.INTERNET" }]

Your app needs read access to the selected file. Use HTTPS in production.

Create an API key in Note → Settings → API Key. It includes the service address. Your app supplies apiKey and filePath below. Generate an idempotencyKey once per new upload and save it with the file reference before uploading. Reuse the saved value when resuming.

Run inside an async method:

import { util } from '@kit.ArkTS';
import { NoteClient, NoteCancellation, RecordingStatus } from '@olares/note-sdk';

const client = NoteClient.fromApiKey(apiKey);
const signal = new NoteCancellation();
const idempotencyKey = util.generateRandomUUID();
// Save idempotencyKey with the file reference before uploading.
const recording = await client.upload(filePath, {
  title: 'Weekly meeting',
  idempotencyKey: idempotencyKey,
  signal: signal,
  onProgress: (sent: number, total: number): void => { /* Confirmed bytes / total bytes. */ }
});
// Save recording.recordingId for later queries.
const result = await client.waitForCompletion(recording.recordingId, {
  signal: signal,
  onStatus: (status: RecordingStatus): void => { /* Show status.processing.currentStage. */ }
});

Upload success means Note has accepted the file; processing may still be running. Save the returned recording ID and query it. Processing failures are returned as statuses; check processing.status.

Network methods return Promise<RecordingStatus> and reject on request failure. RequestOptions accepts an optional cancellation signal.

Byte buffers and URI uploads require fileName with an extension. URI uploads copy to cache and need free space equal to the file size; keep read permission. For manual chunks, use the server's upload.offset and upload.chunkSize; the last chunk may be smaller.

const recording = await client.uploadUri(uri, context.cacheDir, {
  fileName: 'meeting.m4a', idempotencyKey: idempotencyKey, signal: signal
});
const status = await client.getStatus(recording.recordingId, { signal: signal });

UploadOptions accepts these optional fields. Omitted recording settings use Note defaults.

Title, language, target language, source app/device and file name allow up to 2,000 characters each; longer values return field_too_long.

WaitOptions accepts interval = 5000, optional timeout, onStatus and signal. Times are nonnegative safe-integer milliseconds; the default wait is unlimited. The timeout is checked between requests and does not interrupt a request in flight. Use signal.cancel() to stop local work. A zero timeout still permits the first query.

RecordingStatus contains:

Import isFinished(status) to check for a terminal outcome. Read upload.error when upload state is failed. Processing ends at completed, failed or canceled; outcome = no_speech means no speech was detected.

processing.waiting describes a model wait. Its reason is model_unavailable, model_warming, model_busy or model_stalled; use a generic message for unknown values. It also carries capability, RFC 3339 timestamps since / nextProbeAt, and optional message. Keep querying: model recovery can continue processing without another upload.

• Resume with the same file, API key and saved idempotency key. Keep the file unchanged and readable. After upload returns, save recordingId and query directly.
• Your app owns upload records, key storage and task queues. The SDK does not save them or schedule work after restart.
• Create one NoteCancellation per operation; a canceled token cannot be reused. signal.cancel() rejects with NoteCanceledError. It stops local work, without deleting recordings or stopping processing in Note.
• Request failures reject with NoteApiError. Client creation can also fail on an invalid key or address. Handle code; use status (HTTP status, or 0 locally), requestId and retryable for diagnostics and retry decisions. Never log API keys.
• Each request has at most 3 attempts by default, with backoff starting at 500 ms. POST requests retry only with a nonblank idempotency key.

The ArkUI demo in olares-note-harmony-demo-0.2.4-source.zip has ArkTS examples, file selection and local history separated by API key. It demonstrates manual recovery after restart.

AGPL-3.0-only