🚀 Complete WebRTC Implementation Tutorial

This comprehensive tutorial walks through the actual implementation of one-to-one video calls in a Rails app using WebRTC and Action Cable. Every code snippet comes from a working project.

📋 What We’re Building

A Rails app where users can:

• See who’s online in a WhatsApp-style user list
• Click to start video calls with other users
• Accept/decline incoming calls
• Have real-time video/audio conversations

🛠️ Tech Stack

• Rails 7.1.3 + PostgreSQL
• Devise for authentication
• Action Cable for real-time signaling
• WebRTC for peer-to-peer video/audio
• Stimulus for frontend logic

📊 Project Setup

Step 1: Create Call Model

# Generate the Call model with all necessary fields
rails generate model Call caller:references callee:references status:string call_type:string room:string
rails db:migrate
      

Step 2: Add Online Status to Users

# Add online status to track which users are currently active
rails generate migration AddOnlineToUsers online:boolean
rails db:migrate
      

🏗️ Models & Associations

User Model (app/models/user.rb)

class User < ApplicationRecord
  # Devise authentication modules
  devise :database_authenticatable, :registerable,
         :recoverable, :rememberable, :validatable

  # Call associations - a user can be either caller or callee
  has_many :outgoing_calls, class_name: 'Call', foreign_key: :caller_id
  has_many :incoming_calls, class_name: 'Call', foreign_key: :callee_id
end
      

Call Model (app/models/call.rb)

class Call < ApplicationRecord
  belongs_to :caller, class_name: 'User'
  belongs_to :callee, class_name: 'User'

  validates :status, presence: true
  validates :call_type, presence: true
  validates :room, presence: true, uniqueness: true
end
      

📡 Action Cable Channels

UserChannel (app/channels/user_channel.rb)

class UserChannel < ApplicationCable::Channel
  def subscribed
    stream_from "user_#{current_user.id}"
  end
end
      

CallChannel (app/channels/call_channel.rb)

class CallChannel < ApplicationCable::Channel
  def subscribed
    stream_from "call_#{params[:room]}"
  end

  def receive(data)
    ActionCable.server.broadcast("call_#{params[:room]}", data)
  end
end
      

🎮 Controllers & Routes

Routes (config/routes.rb)

Rails.application.routes.draw do
  devise_for :users
  get 'dashboard', to: 'dashboard#index'
  
  resources :calls, only: [:create] do
    member do
      get :room
      post :accept
      post :decline
    end
  end
end
      

Calls Controller (app/controllers/calls_controller.rb)

class CallsController < ApplicationController
  before_action :authenticate_user!

  def create
    callee = User.find(params[:user_id])
    call = Call.create!(
      caller: current_user,
      callee: callee,
      status: "pending",
      call_type: params[:type],
      room: SecureRandom.uuid
    )
    
    ActionCable.server.broadcast("user_#{callee.id}", {
      type: "incoming_call",
      call_id: call.id,
      caller_name: current_user.email,
      call_type: call.call_type,
      room: call.room
    })
    
    render json: { call_id: call.id, room: call.room }, status: :created
  end

  def accept
    call = Call.find(params[:id])
    call.update!(status: "accepted")
    
    [call.caller_id, call.callee_id].each do |user_id|
      ActionCable.server.broadcast("user_#{user_id}", {
        type: "call_accepted",
        call_id: call.id,
        room: call.room
      })
    end
    head :ok
  end

  def room
    @call = Call.find(params[:id])
    unless [@call.caller_id, @call.callee_id].include?(current_user.id)
      redirect_to dashboard_path, alert: 'You are not a participant in this call.'
      return
    end
  end
end
      

🎯 Frontend: Stimulus Controllers

User Call Controller (app/javascript/controllers/user_call_controller.js)

import { Controller } from "@hotwired/stimulus"
import consumer from "channels/consumer"

export default class extends Controller {
  connect() {
    this.currentUserId = this.element.dataset.currentUserId
    this.subscribeToUserChannel()
    this.setupCallButtons()
  }

  subscribeToUserChannel() {
    this.userChannel = consumer.subscriptions.create(
      { channel: "UserChannel" },
      {
        received: (data) => this.handleUserNotification(data)
      }
    )
  }

  handleUserNotification(data) {
    if (data.type === "incoming_call") {
      this.showIncomingCallModal(data)
    } else if (data.type === "call_accepted") {
      window.location.href = `/calls/${data.call_id}/room`
    }
  }

  startCallRequest(userId, type) {
    fetch('/calls', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]').content
      },
      body: JSON.stringify({ user_id: userId, type: type })
    })
    .then(res => res.json())
    .then(data => {
      this.pendingCall = data
      this.showWaitingModal()
    })
  }
}
      

🔗 WebRTC Integration

Call Controller (app/javascript/controllers/call_controller.js)

import { Controller } from "@hotwired/stimulus"
import consumer from "channels/consumer"

export default class extends Controller {
  static targets = ["localVideo", "remoteVideo", "endCallBtn"]

  connect() {
    this.isCaller = localStorage.getItem('isCaller') === 'true'
    localStorage.removeItem('isCaller')
    
    const pathMatch = window.location.pathname.match(/\/calls\/(\d+)\/room/)
    if (pathMatch) {
      this.room = pathMatch[1]
      this.startWebRTCCall(this.room)
    }
  }

  async startWebRTCCall(room) {
    this.room = room
    this.localStream = null
    this.remoteStream = null
    this.peerConnection = null
    this.signaling = null
    
    this.setupSignaling()
    await this.startLocalStream()
    
    if (this.isCaller) {
      this.createOffer()
    }
  }

  setupSignaling() {
    this.signaling = consumer.subscriptions.create(
      { channel: "CallChannel", room: this.room },
      {
        received: (data) => this.handleSignalingData(data)
      }
    )
  }

  async startLocalStream() {
    this.localStream = await navigator.mediaDevices.getUserMedia({ 
      video: true, 
      audio: true 
    })
    this.localVideoTarget.srcObject = this.localStream
  }

  createPeerConnection() {
    this.peerConnection = new RTCPeerConnection({
      iceServers: [
        { urls: "stun:stun.l.google.com:19302" }
      ]
    })
    
    this.localStream.getTracks().forEach(track => {
      this.peerConnection.addTrack(track, this.localStream)
    })
    
    this.peerConnection.ontrack = (event) => {
      if (!this.remoteStream) {
        this.remoteStream = new MediaStream()
        this.remoteVideoTarget.srcObject = this.remoteStream
      }
      event.streams[0].getTracks().forEach(track => {
        this.remoteStream.addTrack(track)
      })
    }
    
    this.peerConnection.onicecandidate = (event) => {
      if (event.candidate) {
        this.sendSignal({ type: "candidate", candidate: event.candidate })
      }
    }
  }

  async createOffer() {
    this.createPeerConnection()
    const offer = await this.peerConnection.createOffer()
    await this.peerConnection.setLocalDescription(offer)
    this.sendSignal({ type: "offer", sdp: offer })
  }

  async handleSignalingData(data) {
    if (data.type === "offer" && !this.isCaller) {
      this.createPeerConnection()
      await this.peerConnection.setRemoteDescription(new RTCSessionDescription(data.sdp))
      const answer = await this.peerConnection.createAnswer()
      await this.peerConnection.setLocalDescription(answer)
      this.sendSignal({ type: "answer", sdp: answer })
    } else if (data.type === "answer" && this.isCaller) {
      await this.peerConnection.setRemoteDescription(new RTCSessionDescription(data.sdp))
    } else if (data.type === "candidate") {
      if (this.peerConnection && this.peerConnection.remoteDescription) {
        await this.peerConnection.addIceCandidate(new RTCIceCandidate(data.candidate))
      }
    }
  }

  sendSignal(data) {
    if (this.signaling) {
      this.signaling.send(data)
    }
  }

  endCall() {
    this.sendSignal({ type: "call_ended" })
    this.endCallCleanup(true)
  }

  endCallCleanup(redirect = true) {
    if (this.peerConnection) {
      this.peerConnection.close()
      this.peerConnection = null
    }
    
    if (this.localStream) {
      this.localStream.getTracks().forEach(track => track.stop())
      this.localStream = null
    }
    
    if (redirect) {
      window.location.href = "/dashboard"
    }
  }
}
      

🎨 UI Implementation

Dashboard View (app/views/dashboard/index.html.erb)

<div class="container py-5" data-controller="user-call" data-current-user-id="<%= current_user.id %>">
  <div class="user-list-panel">
    <div class="user-list-header">Chats</div>
    <div class="user-list-scroll">
      
      <% if @online_users.any? %>
        <div class="user-list-group-label">Online</div>
        <% @online_users.each do |user| %>
          <div class="user-list-row" data-user-id="<%= user.id %>">
            <%= image_tag('https://ui-avatars.com/api/?name=' + URI.encode_www_form_component(user.email), class: "user-list-avatar") %>
            <span class="user-list-email"><%= user.email %></span>
            <div class="user-list-actions">
              <%= button_to "Video", calls_path(type: 'video', user_id: user.id), method: :post, class: "user-list-call-btn" %>
              <%= button_to "Audio", calls_path(type: 'audio', user_id: user.id), method: :post, class: "user-list-call-btn" %>
            </div>
          </div>
        <% end %>
      <% end %>
    </div>
  </div>
</div>
      

Call Room View (app/views/calls/room.html.erb)

<div class="call-room-container" data-controller="call" data-turbo="false">
  <div id="callStatus" class="call-status">Connecting...</div>
  
  <div class="call-videos">
    <video id="remoteVideo" class="call-video-main" autoplay playsinline data-call-target="remoteVideo"></video>
    <video id="localVideo" class="call-video-small" autoplay playsinline muted data-call-target="localVideo"></video>
  </div>
  
  <div class="call-controls">
    <button id="endCallBtn" class="btn btn-danger btn-lg" data-action="click->call#endCall">
      End Call
    </button>
  </div>
</div>
      

🔄 Complete Flow Walkthrough

Step-by-Step Call Process:

1. User A clicks “Video Call” on User B
   • user_call_controller.js sends POST to /calls
   • CallsController#create creates Call record
   • Action Cable broadcasts to User B’s channel
2. User B receives incoming call
   • UserChannel receives notification
   • Modal appears with accept/decline buttons
3. User B accepts call
   • POST to /calls/:id/accept
   • Both users get “call_accepted” notification
   • Both redirect to /calls/:id/room
4. WebRTC Connection Setup
   • Both users join CallChannel with room ID
   • Caller creates offer, sends via Action Cable
   • Callee receives offer, creates answer, sends back
   • Both exchange ICE candidates
   • Direct peer-to-peer connection established
5. Video/Audio Streams
   • Local streams attached to video elements
   • Remote streams received via ontrack event
   • Real-time video/audio communication

All code shown is from the actual working project and can be used as a reference for building similar features!