Technical Documentation: miroslavpejic85/mirotalk

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

MiroTalk P2P - Open Source Self-Hosted WebRTC P2P Video Conferencing

Open Source Peer-to-Peer Video Conferencing You Can Self-Host in Minutes

Free, Secure, Fast Real-Time Communication - up to 8K, 60fps. Works in All Browsers and Platforms.

[Recall.ai](https://www.recall.ai/?utm_source=github&utm_medium=sponsorship&utm_campaign=miroslavpejic85-mirotalk) - API for meeting recording

✨ Why MiroTalk P2P?

🚀 Features

• 🎥 Video up to 8K @ 60fps · Screen sharing · Recording · Picture-in-Picture
• 💬 Chat with Markdown & emoji · Collaborative whiteboard · File sharing
• 🤖 ChatGPT (OpenAI) integration · Speech recognition
• 🔒 OIDC auth · Host protection · JWT credentials · Room passwords · Peer-to-peer encryption
• 🔌 REST API · Slack & Mattermost · Embeddable iframe & widget · 133 languages

See all features →

⚡ Quick start

Start in 6 commands:

git clone https://github.com/miroslavpejic85/mirotalk.git
cd mirotalk
cp .env.template .env
cp app/src/config.template.js app/src/config.js
npm install
npm start

Open http://localhost:3000 - done!

🖼️ Camera backgrounds

In Settings > Video > Background, select Off, Blur, or Image. Local PNG, JPEG, and WebP images up to 10 MB are processed in your browser and are not uploaded. Effects appear in your camera preview, outgoing camera video, and camera recordings. Screen sharing remains unaffected, including when sharing your camera and screen together.

Background controls are also available in prejoin and the quick video menu. Select Image, then use the file picker (or Choose image in the quick video menu) to choose or replace an image. The selected filename stays synchronized between prejoin and Video settings.

Effects require WebGL2 and canvas stream capture; blur also requires canvas filter support. MediaPipe Tasks Vision 0.10.21 and its WASM files are lazy-loaded from jsDelivr, and the selfie segmentation model (version 1) is loaded from Google Storage. These hosts must be reachable and permitted by any custom CSP (including WASM execution). Failures fall back to the camera without effects.

Effect output is capped at 1280 x 720 and 15 FPS. Off uses the original camera track without processing. Performance varies by device; background tabs may throttle rendering.

🐳 Docker

Prerequisites: Install Docker Engine and Docker Compose - Image available on Docker Hub

git clone https://github.com/miroslavpejic85/mirotalk.git
cd mirotalk
cp .env.template .env
cp app/src/config.template.js app/src/config.js
cp docker-compose.template.yml docker-compose.yml
docker-compose pull    # optional: pull official image
docker-compose up      # add -d to run in background

Open http://localhost:3000 - done!

Note:
Edit app/src/config.js, .env, and docker-compose.yml to customize your setup.

📚 Documentation

For detailed guides and references, visit the official documentation:

• Our Story
• About
• Self-Hosting Guide
• Automation-scripts
• Configurations
• Rebranding
• Host Protection Mode
• Integration
• Direct Room Join
• REST API Documentation
• Ngrok
• Updates
• WebHook

☁️ Recommended Hosting Providers

To set up your own instance of MiroTalk P2P on a dedicated cloud server, please refer to our comprehensive self-hosting documentation.

🙏 Credits

• ianramzy (html template)
• vasanthv (webrtc-logic)
• fabric.js (whiteboard)
• DiceBear (random avatars)
• Image by ddraw on Freepik (avatar illustrations)

🤝 Contributing

Contributions are welcome and greatly appreciated! Whether it's bug fixes, features, or documentation - every contribution helps.

1. Fork the repository
2. Create your feature branch
3. Run npm run lint before committing
4. Submit a pull request

Have questions? Join our Discord community!

📄 License

MiroTalk P2P is free and open-source under the terms of AGPLv3 (GNU Affero General Public License v3.0). Please respect the license conditions, In particular modifications need to be free as well and made available to the public. Get a quick overview of the license at Choose an open source license.

To obtain a MiroTalk P2P license with terms different from the AGPLv3, you can conveniently make your purchase on CodeCanyon. This allows you to tailor the licensing conditions to better suit your specific requirements.

❤️ Support the project

Do you find MiroTalk P2P indispensable for your needs? Join us in supporting this transformative project by becoming a backer or sponsor. By doing so, not only will your logo prominently feature here, but you'll also drive the growth and sustainability of MiroTalk P2P. Your support is vital in ensuring that this valuable platform continues to thrive and remain accessible for all. Make an impact - back MiroTalk P2P today and be part of this exciting journey!

🙏 Past Sponsors

We are grateful to our past sponsors for their support!

📢 Advertisers

✨ EffectsSDK

Enhance your video conferencing with advanced virtual backgrounds and noise suppression. EffectsSDK offers powerful SDKs and plugins for fast integration.

• 🎥 AI Video Effects Extension: Virtual backgrounds and effects for your webcam
• 🔊 Noise Cancelling Extension: Clearer audio with background noise reduction
• 🛠️ Integrate EffectsSDK: SDKs and plugins for custom solutions

This project is tested with BrowserStack.

Contributors

Overview (`coturn/README.md`) Copy Section

CoTURN Setup Guide

Set up CoTURN with Docker for NAT traversal and media relay in WebRTC applications.

Installation Steps Copy Chapter

1. Prepare Docker Compose Copy Section

1. Copy the template:
   bash Copy

   cp docker-compose.template.yml docker-compose.yml

2. Edit docker-compose.yml to fit your environment.
3. Use Let's Encrypt and Certbot for SSL certificates. Replace YOUR.DOMAIN in docker-compose.yml with your actual domain name.
   • Learn more about Let's Encrypt: Click here.
   • Learn more about Certbot: Click here.

2. Configure TURN Server Copy Section

1. Copy the template:

   bash Copy

   cp turnserver.template.conf turnserver.conf

2. Edit turnserver.conf:

   • Replace YOUR.DOMAIN.NAME with your domain.
   • Replace YOUR.USERNAME and YOUR.PASSWORD with your credentials.

   Example:

   text Copy

   server-name=example.com
   realm=example.com
   user=username:password

3. Verify Files Copy Section

Ensure turnserver.conf and docker-compose.yml are in the same directory.

4. Start the Server Copy Section

Run:

docker-compose up -d

5. Check Logs (Optional) Copy Section

Check logs to verify the server:

docker-compose logs -f <service_name>

Notes Copy Chapter

• Open ports (e.g., 3478, 5349 for TURN) on your firewall.
• Use secure credentials.
• Test with a WebRTC application.

For more, visit the official documentation.

Overview (`kubernetes/README.md`) Copy Section

k8s deployment

TLDR; and do not care way Copy Chapter

$ make
$ sed -i s/localhost/myshinydomain.tld/g env.txt
$ make prepare
$ make deploy

Understanding way

If you would like to deploy Mirotalk to kubernetes
this set of files can help you in that task

Bellow is explanation of files in this folder which will form one output file in output folder

../.env.template and your file env.txt that you should prepare Copy Chapter

Configuration file that is for now used to configure deployment
you should copy ../.env.template to current directory as env.txt and edit values inside to your liking

$ cp ../.env.template env.txt

Change values (if nothing else HOST variable must be changed so your ingress would recognize it and send requests to your deployed application),
if you do not have public domain you can use free service called nip.io with domain like p2p.192-168-1-1.nip.io (or sslip.io)

$ sed -i s/localhost/myshinydomain.tld/g env.txt

p2p-deployment.yaml Copy Chapter

Main deployment file where you change image file if you would like to use yours if not official one (image: tag)

p2p-cert.yaml Copy Chapter

This file represent definition of certificate (request) when using Cert Manager to generate letsencrypt or private certificates for your domain will be pulled out from env.txt

p2p-ingress.yaml Copy Chapter

This is generic ingress object in kubernetes that is responsible to route external traffic to mirotalk deployed application and if used in conjuction with p2p-cert.yaml (default) will provide TLS enabled access to your mirotalk instance

p2p-service.yaml Copy Chapter

Service required for ingress to be able to know how to access deployment

Makefile Copy Chapter

Helper file that allows running it to configure application how you would like

after creating and changing configuration file (env.txt) run these two tasks, prepare will create deployment file
and deployment will create configMap from prepared env.txt file.

Please run after reading all this:

$ make
# edit env.txt or use sed as in TLDR section :)
$ make prepare
$ make deploy

Overview (`webhook/README.md`) Copy Section

Webhooks Example

This example shows how to set up a server to listen for MiroTalk P2P webhook events (join, disconnect).

Step 1: Enable Webhooks Copy Section

Edit app/src/config.js to enable webhooks:

webhook: {
    enabled: true, // Enable webhook functionality
    url: 'http://localhost:8888/webhook-endpoint', // Webhook server URL
},

Step 2: Run the Webhook Server Copy Section

1. Install dependencies:

   bash Copy

   npm install

2. Start the server:

   bash Copy

   npm start

Step 3: Webhook Events Copy Section

MiroTalk P2P sends HTTP POST requests to the specified URL with event data:

Example Payload:

{
    "event": "join",
    "data": {}
}

• Events: join, disconnect.
• Data: Includes event and custom data.

Overview (`widgets/README.md`) Copy Section

MiroTalk Widgets

This directory contains embeddable example widgets for MiroTalk that can be integrated into any website or application.

Overview (`app/api/README.md`) Copy Section

Create a Meeting Copy Chapter

To initiate a meeting, send an HTTP request to MiroTalk’s server with your API key. Replace the default secret key in .env with your own.

API_KEY_SECRET=mirotalkp2p_default_secret

Use the following examples to make API calls:

# Node.js
node meeting.js
node join.js
node token.js

# PHP
php meeting.php
php join.php
php token.php

# Python
python3 meeting.py
python3 join.py
python3 token.py # rename token in something else

# Bash
./meeting.sh
./join.sh
./token.sh

The server response will contain a meeting URL that can be embedded in your client using an iframe.

Embed a Meeting Copy Chapter

To embed a meeting in your service or app, use an iframe with the source attribute set to the meeting URL obtained from the HTTP response.

<iframe
    allow="camera; microphone; speaker-selection; display-capture; fullscreen; clipboard-read; clipboard-write; web-share; autoplay; picture-in-picture"
    src="https://p2p.mirotalk.com/join/test"
    style="height: 100vh; width: 100vw; border: 0px;"
></iframe>

Fast Integration Copy Chapter

Integrate video meetings into your website or application quickly by incorporating the following iframe code:

<iframe
    allow="camera; microphone; speaker-selection; display-capture; fullscreen; clipboard-read; clipboard-write; web-share; autoplay; picture-in-picture"
    src="https://p2p.mirotalk.com/newcall"
    style="height: 100vh; width: 100vw; border: 0px;"
></iframe>

Overview (`app/ssl/README.md`) Copy Section

Expose MiroTalk on HTTPS Copy Chapter

Generate a self-signed certificate

# install openssl 4 ubuntu
apt install openssl
# install openssl 4 mac
brew install openssl

# self-signed certificate
openssl genrsa -out key.pem
openssl req -new -key key.pem -out csr.pem
openssl x509 -req -days 9999 -in csr.pem -signkey key.pem -out cert.pem
rm csr.pem

# https://www.sslchecker.com/certdecoder

Overview (`public/lang/README.md`) Copy Section

In-room UI translations

Configuration Copy Chapter

Set brand.app.language and brand.app.translationMode in your app
configuration; see config.template.js. The
default language is en; the default translation mode is google.

In a room, users can override the translation mode from Settings > Language.
The mode override is persisted in browser local storage and reused in
subsequent rooms on the same browser.
When users change translation mode, the app shows a short notice and reloads
the page so the selected mode can be fully applied.

Mode override precedence is: browser override → server config default.

Adding a language Copy Chapter

1. Copy en.json to a file named for the language code, such as
   hu.json.
2. Translate the values, keeping the English keys unchanged.
3. Add the language code, flag, and native name to LANG_DISPLAY in
   i18n.js. For right-to-left languages, also add the code to
   RTL_LANGS.
4. Set brand.app.language to the language code and
   brand.app.translationMode to auto or native.

Namespaces Copy Chapter

Fallback behavior Copy Chapter

Missing namespaces, keys, or empty values use the original English text, so
translations can be added incrementally. Keep keys, including their punctuation
and casing, identical to the English source. Preserve placeholders such as
{name} in translated values.

In auto mode, Google Translate is used if the language file is unavailable.
When a native file is loaded, missing entries remain English; they do not fall
back individually to Google Translate.

Synchronize translation keys Copy Chapter

After changing in-room UI strings, run this from the repository root:

npm run lang

The script regenerates en.json and synchronizes other language files,
preserving existing translations, keeping keys in the same order as en.json,
adding missing keys with English values, and removing stale keys. Review the
changes before committing.

Coturn (`docs/coturn.md`) Copy Section

Install Coturn STUN/TURN server

What are STUN and TURN in the context of network communication? Copy Section

https://docs.mirotalk.com/coturn/stun-turn/

How can I set up and configure my own STUN and TURN servers? Copy Section

https://docs.mirotalk.com/coturn/installation/

Ngrok (`docs/ngrok.md`) Copy Section

MiroTalk P2P - Ngrok

What is the purpose and functionality of Ngrok? Copy Section

https://docs.mirotalk.com/ngrok/ngrok/

How to exposing MiroTalk P2P with Ngrok? Copy Section

https://docs.mirotalk.com/mirotalk-p2p/ngrok/

Self Hosting (`docs/self-hosting.md`) Copy Section

MiroTalk P2P - Self Hosting

How can I self-host MiroTalk P2P on my own server? Copy Section

https://docs.mirotalk.com/mirotalk-p2p/self-hosting/

Automation scripts Copy Section

https://docs.mirotalk.com/scripts/about/

--- METRICS ---

• Files Extracted: 11
• Estimated Token Budget: ~7209 tokens
• Canonical Reference: https://codewiki.google/github.com/miroslavpejic85/mirotalk