Starting & Stopping a Recording

Most apps only ever need Picto — see Quick Start. This page also covers PictoService, the lower-level primitive Picto itself is built on, for apps that want more direct control (e.g. the reference app's standalone mode, which runs with no backend configured at all — see apps/mobile/lib/main.dart).

The usual way: Picto#

Picto.startRecording();

A no-op if already recording. Nothing starts a recording automatically — not Picto.ensureInitialized, not any app lifecycle event — this call is the only way one begins. See Quick Start for why.

Ending a session happens two ways: automatically, when the app is backgrounded or terminated, or manually via:

final ok = await Picto.endSessionAndUpload();

The lower-level primitive: PictoService#

PictoService wraps a CanvasRecorder and exposes the same start/stop/tag primitives Picto itself calls internally — construct it wherever you need it (it's a cheap, stateless wrapper — the actual recorder state lives on the CanvasRecorder you pass in, not the service object itself):

final service = PictoService(canvasRecorder);

Checking whether recording is active#

if (service.isRecording) { ... }

Starting#

service.startRecording();

A no-op if already recording. If the recorder was constructed with startActive: false, this is what actually turns it on.

Ending a session#

final segment = await service.endSession();

This stops the recorder (no further activity is captured) and flushes everything recorded so far to an automatically-chosen file under Directory.systemTemp — you never need to come up with a path yourself. The returned RecordingSegment has two fields:

A user can start a fresh recording at any point during their time in the app; each one is a complete, independent recording uploaded on its own — this SDK does not stitch multiple recordings together into one longer session.

The built-in duration cap#

A CanvasRecorder stops accepting new events automatically once a session has been recording for 5 minutes — uploads are single-shot per session, not a continuous stream, so this cap is what stops a runaway session from growing forever before it's ever flushed. flush/endSession still work normally past the cap; they just return whatever was captured up to that point. There's no supported public API to change this ceiling today (the constant backing it is explicitly marked test-only in source) — if 5 minutes is a real constraint for your use case, plan sessions around it rather than trying to override it.