Two posts on this blog give the same advice in a single sentence. Wrap the SDK so "join", "publish" and "record" are your verbs, and a future migration becomes an adapter swap. Put a thin layer of your own in front of it, and it turns a re-platform from a rewrite into a swap of one adapter.
Both are right, and neither shows how. A video SDK abstraction layer that actually holds is more than a wrapper class around the vendor's client. It has four sides, and the one most teams skip is the one that makes leaving expensive.
What a video SDK abstraction layer is, and what it is not
The pattern has a name. Alistair Cockburn described it in 2005 as ports and adapters, with the aim of letting an application be "developed and tested in isolation from its eventual run-time devices and databases". Your product talks to a port it defines. Each provider gets an adapter that implements that port. The provider's types never cross into the rest of your code.
What it is not: a promise that switching becomes free, or a lowest-common-denominator API that hides every useful feature. The goal is narrower. When you do switch, the change should be one adapter and its tests, not every file that touches video.
The four sides of the seam
The layers of what a provider switch rewrites tell you where the seam has to run:
Side | What you own | What stays inside the adapter |
|---|---|---|
1. Client | The verbs your UI calls and the events it listens to | The vendor SDK, its objects and event names |
2. Server | One token service, room lifecycle, webhook intake | Each vendor's token format and REST calls |
3. Identity | Your room, participant and session IDs | A mapping table to vendor IDs |
4. Data | Where recordings live and how they are referenced | The vendor's recording API |
Most "wrap the SDK" advice covers only side one. Sides three and four are what turn a migration into an archive project.
Side 1: the client interface
Start from what your product does, not from what the SDK offers. An illustrative interface, in TypeScript:
interface VideoSession {
join(room: RoomId, token: SessionToken): Promise<void>;
leave(): Promise<void>;
publish(source: 'camera' | 'microphone' | 'screen'): Promise<LocalTrack>;
subscribe(who: ParticipantId, quality: QualityHint): Promise<RemoteTrack>;
on<E extends SessionEvent>(event: E, handler: Handler<E>): Unsubscribe;
capabilities(): Capabilities;
}
Four rules make it hold:
- Your IDs, not theirs. RoomId and ParticipantId are your types. The adapter maps them to whatever the vendor uses.
- Subscription is in the interface, with a quality hint. On some providers what each user receives is a pricing decision: Agora, for example, bills on the total resolution each user subscribes to. If subscription control lives inside the vendor's UI kit, so does your bill.
- Limits are declared, not discovered. capabilities() reports what this adapter can do: maximum rendered videos, maximum resolution, screen share support. Zoom's web SDK, for instance, renders up to 25 videos on desktop and 4 on mobile. Your layout code reads the number instead of assuming it.
- No vendor types in UI state. If a vendor's participant object ends up in your state store, the seam has a hole in it, and every component that reads that store is now part of the migration.
Side 1, continued: your events, your meanings
Events are where seams leak. Define your own vocabulary (participantJoined, participantLeft, trackAvailable, activeSpeakerChanged) and decide what each one means in your product.
Then make the adapter responsible for that meaning, not just the name. Zoom's active-speaker event fires once someone has been talking for more than a second; another provider's may use a different rule. If your product needs a specific behaviour, such as a 1.5-second hold before the speaker view switches, implement it in your layer, once, so it stays the same when the adapter changes.
Side 2: one server-side seam
Every provider needs a backend to issue credentials, and each issues a different kind. Put all of it behind one service you own:
- One token endpoint. Your client asks your backend for a session token for a RoomId. Which vendor format comes back is the adapter's business.
- One room lifecycle. Create, end and look up rooms through your API, keyed on your IDs.
- One webhook intake. Vendor callbacks arrive at an adapter that translates them into your own events and writes them to your own store. The rest of your backend never parses a vendor payload.
Sides 3 and 4: identity and recordings
These are the sides that make leaving expensive, and the cheapest to get right on day one.
Identity. Keep a mapping table from your room and participant IDs to each vendor's, with timestamps. Support tickets, analytics and audit trails reference your IDs. When the provider changes, the history still resolves.
Recordings. Write them to storage you own from the first recording. Twilio can send recordings to your own S3 bucket instead of its cloud; Daily can write directly to your bucket without storing them at all. Reference recordings by your own IDs and paths. Then a provider switch changes where new recordings come from, not where old ones live.
Proving the seam
A seam with one adapter is a hypothesis. Two things turn it into a fact.
- A contract test suite written against the interface, not the vendor: join, publish, subscribe at each quality hint, receive each event, leave. Every adapter must pass it.
- A second adapter. It does not have to be a second provider. An in-memory fake that passes the same contract tests proves that nothing outside the adapter depends on the vendor, and it is exactly the "tested in isolation" that ports and adapters were described for.
If the fake cannot pass without changes elsewhere in your code, you have found the leak before a migration did.
What the seam costs
The honest part: an abstraction layer is a component you maintain, and it has real costs.
- It lags the vendor. A new SDK feature is not available to your product until someone exposes it through the interface.
- It can flatten useful differences. The fix is capabilities, not a smaller interface: expose provider-specific features as optional capabilities your UI can check for.
- Prebuilt UI kits sit outside it. A vendor's drop-in meeting UI is the fastest way to ship, and it puts the vendor's components straight into your interface. When Dyte became RealtimeKit, its UI kits were renamed along with everything else. If you use one, accept that the UI is part of any migration.
So the seam is not always worth building. A product that embeds a vendor UI on one screen, at low volume, may be better off shipping and accepting the rewrite risk. The seam earns its cost when video is core to the product, when the integration is custom, or when your provider could be acquired, deprecated or shut down on a timeline you do not control.
Where to draw the line
Keep behind the seam | Let through as a declared capability |
|---|---|
Join, leave, publish, subscribe | Vendor-specific effects, filters, noise suppression |
Participant and room identity | Maximum rendered videos and resolution |
Event names and their meaning | Provider-only features such as built-in transcription |
Tokens, room lifecycle, webhooks | Diagnostic data unique to one provider |
Recording storage and references | — |
The Bottom Line
A video SDK abstraction layer is a port your product owns and an adapter per provider. To hold, it has to cover four sides: client verbs and events, the server that issues tokens and receives webhooks, your own identity, and recordings in your own storage. Prove it with contract tests and a second adapter, accept that it costs maintenance, and build it before the code spreads, because afterwards it is a migration of its own.
What's Next
A seam decides how expensive it is to leave. The other half of the decision is who gets paged when it fails under each path, and how long recovery takes.
Frequently Asked Questions
What is a video SDK abstraction layer?
An interface your application owns for joining calls, publishing and subscribing to media, handling events and recording, with one adapter per video provider that implements it. The provider's types stay inside the adapter, so changing provider means changing one adapter rather than every file that touches video.
Does an abstraction layer make switching video providers free?
No. It turns the switch into writing and testing one new adapter, plus whatever provider-specific capabilities your product relies on. It also helps most when identity and recordings are already under your control, since those are the parts code changes cannot fix.
What should a video SDK interface include?
At minimum: join, leave, publish, subscribe with a quality hint, an event subscription using your own event names, and a capabilities call that reports limits such as maximum rendered videos. On the server side: one token endpoint, room lifecycle and webhook intake.
How do I test a video abstraction layer?
Write contract tests against your interface, not the vendor, and run every adapter through them. An in-memory fake adapter that passes the same tests proves that nothing outside the adapter depends on the provider.
Should I use a video provider's prebuilt UI kit?
It is the fastest way to ship, but it puts the vendor's components directly into your product, outside any abstraction layer. If you use one, treat the UI as part of any future migration.
Does Samvyo work behind an abstraction layer?
Yes, the same way as any provider. Samvyo, based on SFU architecture, ships embeddable SDKs like a cloud video API, with the media path, TURN and recording kept on infrastructure you control, which means the recording side of the seam is already in your own storage.
