When two browsers send a file to each other, it can look like magic. You drop a file, the other tab starts receiving bytes, and nothing obvious like a cloud folder appears in the middle. Under the hood, that path is usually WebRTC—a set of browser APIs originally built for real-time audio and video, later used for arbitrary data.
\nWebRTC file transfer is not one protocol with a single happy path. It is a negotiation: discover public addresses, punch through NAT if possible, fall back to a relay if not, then open an encrypted data channel. This guide walks through that pipeline in practical terms, including when peer-to-peer fails and when a room-style upload is the better engineering choice.
\nWebRTC is a stack, not a file-sharing product. For files, the important pieces are:
\nA video call uses media tracks. A file transfer uses a data channel. Same ICE dance, different payload. If you only remember one sentence, remember this: the file does not travel over your signaling WebSocket unless you put it there on purpose.
\nBefore two peers can talk, they need a signaling channel—usually a WebSocket or HTTP API on a server you control. Signaling carries SDP offers, answers, and ICE candidates. It coordinates the session. It should not be mistaken for the transfer itself.
\nIf signaling is down, WebRTC never starts. If signaling is up but ICE fails, the UI can still look \"connected\" until you actually test the data channel. That mismatch is why many first implementations look fine in a demo and fail the first time two people join from different mobile networks.
\nMost devices sit behind NAT. The browser thinks it is `192.168.1.42:54321`. The public internet sees something else. For a peer to send packets back, that mapping must be discovered and kept alive.
\nA STUN server answers a simple question: what do I look like from the public internet? The client adds that reflexive address as an ICE candidate. If both sides sit behind cooperative consumer NAT, hole punching often works. Symmetric NAT, carrier-grade NAT on mobile, hotel double NAT, and locked-down office firewalls frequently break the direct path.
\nWhen every direct candidate fails, TURN relays the bytes through a server. The transfer can still use WebRTC APIs and still encrypt the channel, but you now pay for bandwidth, and the relay sees connection metadata such as timing and volume.
\nPractical rule of thumb:
\nDo not promise users \"direct, no server\" if you have not provisioned TURN. Without a relay, a large share of real-world pairs never connect. That is not a bug in your chunking code. It is the internet.
\nOnce ICE selects a candidate pair and DTLS completes, you open an RTCDataChannel. A typical file protocol looks like this:
\nDefault data channels are reliable and ordered, which is what most file tools want. Unordered or unreliable modes exist for games and lossy real-time data. They are the wrong default for an APK, a zip, or a crash dump.
\nWatch these gotchas:
\nP2P is a best effort, not a guarantee. Common failure modes:
\nWhen P2P fails, you have two honest product choices:
\nChoose a non-P2P or hybrid path when:
\nBrowser room tools such as [PeerPizza](/) take the temporary-room approach: no account, a room code, optional PIN, chat plus files, chunked uploads without a fixed per-file size cap, and automatic cleanup after roughly two hours of inactivity. That is a different tradeoff from a live WebRTC pipe. Keep a local backup either way—temporary rooms expire on purpose.
\nOther options include self-hosted object storage, signed cloud URLs, or a TURN-backed WebRTC product if both people can stay online. The right answer depends on whether \"both tabs open right now\" is a reasonable requirement.
\nWebRTC data channels are encrypted with DTLS. That is necessary and not sufficient.
\nWebRTC does not remove the need for ordinary access control. It only encrypts the path you already decided to open.
\nIf you are building or evaluating a WebRTC file feature, require these before you call it production:
\nA checklist will not make NAT disappear. It will stop you from shipping a demo that only works on the same Wi-Fi.
\nUse this section when localhost works and production does not.
\n| Concern | Live WebRTC data channel | Temporary room or cloud upload |
|---|---|---|
| Both users online | Required | Not required |
| Typical NAT pain | High without TURN | Low (ordinary HTTPS) |
| Extra server bandwidth | Only if TURN is used | Always (upload plus download) |
| Best for | Same session, same time | Async handoff |
| Tab crash or phone lock | Often fatal | Upload can continue independently |
| Long-term archive | No | Only if you keep the object |
Neither model is \"more secure\" by slogan. Security is access control, expiry, and whether the right human received the file.
\nWebRTC file transfer is a live, encrypted pipe assembled from ICE, STUN, optional TURN, and SCTP data channels. It is excellent when two browsers are online together and the network path is kind. It is a poor default when you cannot run TURN, when recipients show up later, or when mobile tabs will sleep. Know the failure modes, put a relay or a temporary room behind the send button, and never confuse \"the packet was encrypted\" with \"the right person got the only copy.\" Keep the original file on disk. Protocols expire. Backups do not have to.
","content_text":"When two browsers send a file to each other, it can look like magic. You drop a file, the other tab starts receiving bytes, and nothing obvious like a cloud folder appears in the middle. Under the hood, that path is usually WebRTC—a set of browser APIs originally built for real-time audio and video, later used for arbitrary data.\n\nWebRTC file transfer is not one protocol with a single happy path. It is a negotiation: discover public addresses, punch through NAT if possible, fall back to a relay if not, then open an encrypted data channel. This guide walks through that pipeline in practical terms, including when peer-to-peer fails and when a room-style upload is the better engineering choice.\n\nWhat WebRTC actually moves\n\nWebRTC is a stack, not a file-sharing product. For files, the important pieces are:\n\n- ICE (Interactive Connectivity Establishment) to gather candidate network paths\n- STUN servers to learn your public IP and port mapping\n- TURN servers to relay traffic when direct paths fail\n- DTLS for encrypting the data channel\n- SCTP data channels to send bytes that are not audio or video\n\nA video call uses media tracks. A file transfer uses a data channel. Same ICE dance, different payload. If you only remember one sentence, remember this: the file does not travel over your signaling WebSocket unless you put it there on purpose.\n\nSignaling is not the file path\n\nBefore two peers can talk, they need a signaling channel—usually a WebSocket or HTTP API on a server you control. Signaling carries SDP offers, answers, and ICE candidates. It coordinates the session. It should not be mistaken for the transfer itself.\n\nIf signaling is down, WebRTC never starts. If signaling is up but ICE fails, the UI can still look \"connected\" until you actually test the data channel. That mismatch is why many first implementations look fine in a demo and fail the first time two people join from different mobile networks.\n\nNAT, STUN, and why home networks fight you\n\nMost devices sit behind NAT. The browser thinks it is `192.168.1.42:54321`. The public internet sees something else. For a peer to send packets back, that mapping must be discovered and kept alive.\n\nA STUN server answers a simple question: what do I look like from the public internet? The client adds that reflexive address as an ICE candidate. If both sides sit behind cooperative consumer NAT, hole punching often works. Symmetric NAT, carrier-grade NAT on mobile, hotel double NAT, and locked-down office firewalls frequently break the direct path.\n\nTURN is the expensive honest fallback\n\nWhen every direct candidate fails, TURN relays the bytes through a server. The transfer can still use WebRTC APIs and still encrypt the channel, but you now pay for bandwidth, and the relay sees connection metadata such as timing and volume.\n\nPractical rule of thumb:\n\n- Same LAN or same Wi-Fi: host candidates often win and feel instant.\n- Home to home on typical consumer NAT: STUN is often enough.\n- Corporate, campus, or mobile CGNAT: budget for TURN, or skip live P2P.\n\nDo not promise users \"direct, no server\" if you have not provisioned TURN. Without a relay, a large share of real-world pairs never connect. That is not a bug in your chunking code. It is the internet.\n\nData channels: how the file actually moves\n\nOnce ICE selects a candidate pair and DTLS completes, you open an RTCDataChannel. A typical file protocol looks like this:\n\n1. Exchange metadata: name, size, MIME type, optional hash.\n2. Slice the file into chunks, often 16–64 KB.\n3. Send chunks with sequence numbers.\n4. Apply backpressure with `bufferedAmount` and `bufferedAmountLowThreshold`.\n5. Reassemble and verify on the receiver before you call the transfer done.\n\nOrdered vs unordered, reliable vs partial\n\nDefault data channels are reliable and ordered, which is what most file tools want. Unordered or unreliable modes exist for games and lossy real-time data. They are the wrong default for an APK, a zip, or a crash dump.\n\nWatch these gotchas:\n\n- `bufferedAmount` can explode if you `send()` as fast as the disk reads. Pause when the buffer is high.\n- Mobile browsers background tabs and freeze timers. Transfers stall when the phone sleeps.\n- Chunk size vs overhead: huge chunks delay the first progress tick; tiny chunks waste CPU.\n- Memory: reading a multi-gigabyte file into one `ArrayBuffer` can kill a tab. Stream with `Blob.slice` or readable streams.\n\nWhen peer-to-peer fails (and you should expect it)\n\nP2P is a best effort, not a guarantee. Common failure modes:\n\n- One peer is on a VPN that blocks UDP.\n- School or office firewalls allow only HTTPS on 443/TCP.\n- Both peers sit behind symmetric NAT.\n- The page is not a secure context, so the browser refuses WebRTC features.\n- One user closes the tab. There is no daemon holding the socket.\n- IPv6 and IPv4 mismatch with incomplete ICE candidates.\n\nWhen P2P fails, you have two honest product choices:\n\n1. TURN relay — still WebRTC, still a live session, both users online at once.\n2. Room or store-and-forward upload — sender uploads to temporary storage; the receiver downloads later over ordinary HTTPS.\n\nWhen a relay or room upload is better\n\nChoose a non-P2P or hybrid path when:\n\n- Recipients will download hours later.\n- You need more than two people without building a full mesh.\n- Mobile users will lock their phones mid-transfer.\n- You cannot operate a reliable TURN fleet.\n- Compliance needs a server-side scan or an audit log.\n\nBrowser room tools such as PeerPizza take the temporary-room approach: no account, a room code, optional PIN, chat plus files, chunked uploads without a fixed per-file size cap, and automatic cleanup after roughly two hours of inactivity. That is a different tradeoff from a live WebRTC pipe. Keep a local backup either way—temporary rooms expire on purpose.\n\nOther options include self-hosted object storage, signed cloud URLs, or a TURN-backed WebRTC product if both people can stay online. The right answer depends on whether \"both tabs open right now\" is a reasonable requirement.\n\nSecurity caveats developers skip\n\nWebRTC data channels are encrypted with DTLS. That is necessary and not sufficient.\n\n- Signaling is the trust boundary. If an attacker joins the room or intercepts the offer, they become a peer. Authenticate signaling. Use short-lived room tokens. Offer a PIN when the content is sensitive.\n- You still share a file with a person. Encryption to the wrong recipient is a successful attack, not a crypto failure.\n- TURN operators can see metadata even if payloads stay encrypted: who connected, how much, and when.\n- Do not treat STUN or TURN credentials as immortal secrets. Issue time-limited credentials.\n- Hash the file if integrity matters. Accidental truncation can look like success if you only watch `onclose`.\n- Short public room codes can be guessed. Rate-limit room creation. Log enough to handle abuse reports without keeping files forever.\n\nWebRTC does not remove the need for ordinary access control. It only encrypts the path you already decided to open.\n\nA practical architecture checklist\n\nIf you are building or evaluating a WebRTC file feature, require these before you call it production:\n\n- HTTPS (a secure context) on every page that opens a peer connection\n- Signaling with authentication or unguessable room IDs\n- STUN plus TURN with metering, not STUN alone\n- Chunked send with backpressure\n- Progress on both sides, including a clear failed state\n- Size or hash verification at the end\n- UX that explains the live-session rule: both people stay online, or they should use a room upload instead\n\nA checklist will not make NAT disappear. It will stop you from shipping a demo that only works on the same Wi-Fi.\n\nTroubleshooting WebRTC file transfers\n\nUse this section when localhost works and production does not.\n\nConnection never establishes\n\n- Check ICE gathering. Zero candidates besides host usually means the STUN URL is wrong, blocked, or never configured.\n- Confirm both peers receive remote candidates over signaling. A one-way signaling bug looks exactly like a NAT problem.\n- Ask one side to disable VPN and try again.\n- Test with a known-good TURN server. If TURN works and host or server-reflexive candidates fail, NAT is the story.\n\nChannel opens, then the transfer stalls\n\n- Log `bufferedAmount`. If it only grows, you are not respecting backpressure.\n- Confirm the receiver is handling `onmessage` and not blocked on UI work.\n- Watch for tab freeze on mobile Safari when the screen locks.\n- Avoid huge `send()` payloads that hit browser message-size limits.\n\nFile arrives corrupted or truncated\n\n- Compare byte length before you celebrate.\n- Compute a SHA-256 of the blob on both sides for important artifacts.\n- Do not drop the last chunk when `readyState` flips to closing.\n- Avoid treating `bufferedAmount === 0` as \"the other side has the file.\" That only means your local send buffer drained.\n\nFast at the office, slow at home\n\n- Same-network host candidates can hit the LAN. Remote paths go through the slower of two uplinks.\n- Home upload bandwidth is usually the bottleneck, not the data channel API.\n- If TURN is selected, you also pay the relay's path and capacity.\n\nWebRTC vs store-and-forward at a glance\n\n| Concern | Live WebRTC data channel | Temporary room or cloud upload |\n| --- | --- | --- |\n| Both users online | Required | Not required |\n| Typical NAT pain | High without TURN | Low (ordinary HTTPS) |\n| Extra server bandwidth | Only if TURN is used | Always (upload plus download) |\n| Best for | Same session, same time | Async handoff |\n| Tab crash or phone lock | Often fatal | Upload can continue independently |\n| Long-term archive | No | Only if you keep the object |\n\nNeither model is \"more secure\" by slogan. Security is access control, expiry, and whether the right human received the file.\n\nFinal thoughts\n\nWebRTC file transfer is a live, encrypted pipe assembled from ICE, STUN, optional TURN, and SCTP data channels. It is excellent when two browsers are online together and the network path is kind. It is a poor default when you cannot run TURN, when recipients show up later, or when mobile tabs will sleep. Know the failure modes, put a relay or a temporary room behind the send button, and never confuse \"the packet was encrypted\" with \"the right person got the only copy.\" Keep the original file on disk. Protocols expire. Backups do not have to.","word_count":1778,"author":{"name":"Vishvajeet Shukla","url":"https://vishvajeetshukla.in","same_as":["https://vishvajeetshukla.in","https://twitter.com/vishu_07","https://x.com/vishu_07"]},"seo":{"canonical":"https://peerpizza.vercel.app/blog/webrtc-file-transfer-how-it-works"},"citation_policy":{"attribution_required":true,"link_back_required":true,"canonical_field":"url"}}