Eve library

Stream Service gRPC API

Guide

Revision 1

On this page

gRPC API documentation for the Aphrodite Stream Service.

Host: stream.aphrodite.example.com Port: 50051 Protocol: gRPC (HTTP/2) Health Port: 3001 (HTTP)


Table of Contents#

  1. Overview
  2. Protocol Buffers
  3. Services
  4. Authentication
  5. Error Handling

Overview#

The Stream Service uses gRPC for high-performance service-to-service communication, particularly for stream management, signaling, and media coordination.

Connection#

typescript
import { credentials, Metadata } from '@grpc/grpc-js';
import { StreamServiceClient } from '@aphrodite/proto/stream';

const client = new StreamServiceClient(
  'stream.aphrodite.example.com:50051',
  credentials.createSsl()
);

// With authentication
const metadata = new Metadata();
metadata.set('authorization', `Bearer ${serviceToken}`);

Protocol Buffers#

Common Types#

protobuf
// common.proto
syntax = "proto3";
package aphrodite.common.v1;

import "google/protobuf/timestamp.proto";

message Pagination {
  string cursor = 1;
  int32 limit = 2;
}

message PaginationResponse {
  string next_cursor = 1;
  bool has_more = 2;
  int64 total = 3;
}

message Error {
  string code = 1;
  string message = 2;
  map<string, string> details = 3;
}

Stream Messages#

protobuf
// stream.proto
syntax = "proto3";
package aphrodite.stream.v1;

import "google/protobuf/timestamp.proto";
import "common.proto";

enum StreamStatus {
  STREAM_STATUS_UNSPECIFIED = 0;
  STREAM_STATUS_SCHEDULED = 1;
  STREAM_STATUS_STARTING = 2;
  STREAM_STATUS_LIVE = 3;
  STREAM_STATUS_ENDING = 4;
  STREAM_STATUS_ENDED = 5;
  STREAM_STATUS_CANCELLED = 6;
}

enum StreamType {
  STREAM_TYPE_UNSPECIFIED = 0;
  STREAM_TYPE_PUBLIC = 1;
  STREAM_TYPE_PRIVATE = 2;
  STREAM_TYPE_GROUP = 3;
  STREAM_TYPE_TICKET = 4;
}

message Stream {
  string id = 1;
  string creator_id = 2;
  string title = 3;
  string description = 4;
  StreamStatus status = 5;
  StreamType type = 6;
  string category = 7;
  repeated string tags = 8;
  string thumbnail_url = 9;
  google.protobuf.Timestamp scheduled_start = 10;
  google.protobuf.Timestamp started_at = 11;
  google.protobuf.Timestamp ended_at = 12;
  StreamSettings settings = 13;
  StreamStats stats = 14;
}

message StreamSettings {
  bool chat_enabled = 1;
  bool tips_enabled = 2;
  bool devices_enabled = 3;
  int32 max_viewers = 4;
  QualitySettings quality = 5;
  ChatSettings chat = 6;
}

message QualitySettings {
  repeated string available_qualities = 1;
  string default_quality = 2;
  int32 max_bitrate = 3;
  bool low_latency = 4;
}

message ChatSettings {
  bool slow_mode = 1;
  int32 slow_mode_interval = 2;
  bool subscriber_only = 3;
  bool follower_only = 4;
  int32 follower_min_time = 5;
}

message StreamStats {
  int64 current_viewers = 1;
  int64 peak_viewers = 2;
  int64 total_viewers = 3;
  int64 chat_messages = 4;
  double total_tips = 5;
  int64 duration_seconds = 6;
}

message StreamKey {
  string key = 1;
  string rtmp_url = 2;
  string srt_url = 3;
  google.protobuf.Timestamp expires_at = 4;
}

User Messages#

protobuf
// user.proto
syntax = "proto3";
package aphrodite.user.v1;

import "google/protobuf/timestamp.proto";

message User {
  string id = 1;
  string username = 2;
  string display_name = 3;
  string avatar_url = 4;
  bool verified = 5;
  bool is_creator = 6;
  google.protobuf.Timestamp created_at = 7;
}

message Creator {
  string id = 1;
  string user_id = 2;
  string display_name = 3;
  string bio = 4;
  string category = 5;
  repeated string tags = 6;
  bool is_live = 7;
  string current_stream_id = 8;
  CreatorStats stats = 9;
}

message CreatorStats {
  int64 followers = 1;
  int64 subscribers = 2;
  int64 total_streams = 3;
  int64 total_hours = 4;
}

Event Messages#

protobuf
// events.proto
syntax = "proto3";
package aphrodite.events.v1;

import "google/protobuf/timestamp.proto";
import "stream.proto";
import "user.proto";

message StreamStartedEvent {
  string stream_id = 1;
  string creator_id = 2;
  string title = 3;
  google.protobuf.Timestamp started_at = 4;
}

message StreamEndedEvent {
  string stream_id = 1;
  google.protobuf.Timestamp ended_at = 2;
  int64 duration_seconds = 3;
  aphrodite.stream.v1.StreamStats final_stats = 4;
}

message ViewerJoinedEvent {
  string stream_id = 1;
  string user_id = 2;
  google.protobuf.Timestamp joined_at = 3;
}

message ViewerLeftEvent {
  string stream_id = 1;
  string user_id = 2;
  int64 watch_duration_seconds = 3;
  google.protobuf.Timestamp left_at = 4;
}

message TipReceivedEvent {
  string stream_id = 1;
  string tip_id = 2;
  string sender_id = 3;
  double amount = 4;
  string message = 5;
  google.protobuf.Timestamp received_at = 6;
}

message GoalCompletedEvent {
  string stream_id = 1;
  string goal_id = 2;
  string name = 3;
  double target = 4;
  double final_amount = 5;
  google.protobuf.Timestamp completed_at = 6;
}

message EventEnvelope {
  string id = 1;
  string type = 2;
  google.protobuf.Timestamp occurred_at = 3;
  oneof payload {
    StreamStartedEvent stream_started = 10;
    StreamEndedEvent stream_ended = 11;
    ViewerJoinedEvent viewer_joined = 12;
    ViewerLeftEvent viewer_left = 13;
    TipReceivedEvent tip_received = 14;
    GoalCompletedEvent goal_completed = 15;
  }
}

Services#

StreamService#

protobuf
// stream_service.proto
syntax = "proto3";
package aphrodite.stream.v1;

import "stream.proto";
import "common.proto";

service StreamService {
  // Stream Management
  rpc CreateStream(CreateStreamRequest) returns (CreateStreamResponse);
  rpc GetStream(GetStreamRequest) returns (GetStreamResponse);
  rpc UpdateStream(UpdateStreamRequest) returns (UpdateStreamResponse);
  rpc DeleteStream(DeleteStreamRequest) returns (DeleteStreamResponse);
  rpc ListStreams(ListStreamsRequest) returns (ListStreamsResponse);

  // Stream Lifecycle
  rpc StartStream(StartStreamRequest) returns (StartStreamResponse);
  rpc EndStream(EndStreamRequest) returns (EndStreamResponse);

  // Stream Key Management
  rpc GetStreamKey(GetStreamKeyRequest) returns (GetStreamKeyResponse);
  rpc RegenerateStreamKey(RegenerateStreamKeyRequest) returns (RegenerateStreamKeyResponse);

  // Viewer Management
  rpc GetViewers(GetViewersRequest) returns (GetViewersResponse);
  rpc KickViewer(KickViewerRequest) returns (KickViewerResponse);

  // Stream Stats
  rpc GetStreamStats(GetStreamStatsRequest) returns (GetStreamStatsResponse);
  rpc StreamStatsStream(StreamStatsStreamRequest) returns (stream StreamStatsUpdate);

  // Event Subscription
  rpc SubscribeToEvents(SubscribeToEventsRequest) returns (stream EventEnvelope);
}

Request/Response Messages#

CreateStream#

protobuf
message CreateStreamRequest {
  string creator_id = 1;
  string title = 2;
  string description = 3;
  StreamType type = 4;
  string category = 5;
  repeated string tags = 6;
  google.protobuf.Timestamp scheduled_start = 7;
  StreamSettings settings = 8;
}

message CreateStreamResponse {
  Stream stream = 1;
  StreamKey stream_key = 2;
}

GetStream#

protobuf
message GetStreamRequest {
  string stream_id = 1;
}

message GetStreamResponse {
  Stream stream = 1;
}

ListStreams#

protobuf
message ListStreamsRequest {
  string creator_id = 1;
  StreamStatus status = 2;
  StreamType type = 3;
  aphrodite.common.v1.Pagination pagination = 4;
}

message ListStreamsResponse {
  repeated Stream streams = 1;
  aphrodite.common.v1.PaginationResponse pagination = 2;
}

StartStream#

protobuf
message StartStreamRequest {
  string stream_id = 1;
}

message StartStreamResponse {
  Stream stream = 1;
  string ingest_url = 2;
  string playback_url = 3;
}

EndStream#

protobuf
message EndStreamRequest {
  string stream_id = 1;
  bool save_vod = 2;
}

message EndStreamResponse {
  Stream stream = 1;
  string vod_id = 2;
}

StreamStatsStream (Server Streaming)#

protobuf
message StreamStatsStreamRequest {
  string stream_id = 1;
  int32 interval_seconds = 2;
}

message StreamStatsUpdate {
  string stream_id = 1;
  StreamStats stats = 2;
  google.protobuf.Timestamp timestamp = 3;
}

SubscribeToEvents (Server Streaming)#

protobuf
message SubscribeToEventsRequest {
  repeated string stream_ids = 1;
  repeated string event_types = 2;
}

SignalingService#

WebRTC signaling for peer connections.

protobuf
// signaling_service.proto
syntax = "proto3";
package aphrodite.signaling.v1;

service SignalingService {
  // WebRTC Signaling
  rpc CreateOffer(CreateOfferRequest) returns (CreateOfferResponse);
  rpc CreateAnswer(CreateAnswerRequest) returns (CreateAnswerResponse);
  rpc AddIceCandidate(AddIceCandidateRequest) returns (AddIceCandidateResponse);

  // Bidirectional signaling stream
  rpc SignalingStream(stream SignalingMessage) returns (stream SignalingMessage);
}

message CreateOfferRequest {
  string stream_id = 1;
  string session_id = 2;
}

message CreateOfferResponse {
  string sdp = 1;
  string type = 2;
}

message CreateAnswerRequest {
  string stream_id = 1;
  string session_id = 2;
  string sdp = 3;
}

message CreateAnswerResponse {
  string sdp = 1;
  string type = 2;
}

message AddIceCandidateRequest {
  string stream_id = 1;
  string session_id = 2;
  string candidate = 3;
  string sdp_mid = 4;
  int32 sdp_mline_index = 5;
}

message AddIceCandidateResponse {
  bool success = 1;
}

message SignalingMessage {
  string stream_id = 1;
  string session_id = 2;
  oneof message {
    Offer offer = 3;
    Answer answer = 4;
    IceCandidate ice_candidate = 5;
  }
}

message Offer {
  string sdp = 1;
}

message Answer {
  string sdp = 1;
}

message IceCandidate {
  string candidate = 1;
  string sdp_mid = 2;
  int32 sdp_mline_index = 3;
}

MediaService#

Media processing and transcoding.

protobuf
// media_service.proto
syntax = "proto3";
package aphrodite.media.v1;

service MediaService {
  // Transcoding
  rpc StartTranscoding(StartTranscodingRequest) returns (StartTranscodingResponse);
  rpc StopTranscoding(StopTranscodingRequest) returns (StopTranscodingResponse);
  rpc GetTranscodingStatus(GetTranscodingStatusRequest) returns (TranscodingStatus);

  // Recording
  rpc StartRecording(StartRecordingRequest) returns (StartRecordingResponse);
  rpc StopRecording(StopRecordingRequest) returns (StopRecordingResponse);

  // Thumbnails
  rpc GenerateThumbnail(GenerateThumbnailRequest) returns (GenerateThumbnailResponse);
}

message TranscodingProfile {
  string name = 1;
  int32 width = 2;
  int32 height = 3;
  int32 bitrate = 4;
  int32 framerate = 5;
  string codec = 6;
}

message StartTranscodingRequest {
  string stream_id = 1;
  string input_url = 2;
  repeated TranscodingProfile profiles = 3;
  bool enable_hls = 4;
  bool enable_dash = 5;
}

message StartTranscodingResponse {
  string job_id = 1;
  map<string, string> output_urls = 2;
}

message TranscodingStatus {
  string job_id = 1;
  string status = 2;
  map<string, ProfileStatus> profiles = 3;
}

message ProfileStatus {
  string quality = 1;
  int32 bitrate = 2;
  int64 frames_processed = 3;
  double fps = 4;
}

Authentication#

Service-to-Service Authentication#

gRPC calls between services use JWT tokens in metadata:

typescript
const metadata = new Metadata();
metadata.set('authorization', `Bearer ${serviceToken}`);

client.getStream(request, metadata, (err, response) => {
  // Handle response
});

Token Format#

Service tokens contain:

json
{
  "iss": "aphrodite",
  "sub": "stream-service",
  "aud": "aphrodite-services",
  "iat": 1737216000,
  "exp": 1737219600,
  "scope": ["stream:read", "stream:write"]
}

Error Handling#

gRPC Status Codes#

Code HTTP Equiv Description
OK 200 Success
INVALID_ARGUMENT 400 Invalid request parameters
UNAUTHENTICATED 401 Missing or invalid auth
PERMISSION_DENIED 403 Insufficient permissions
NOT_FOUND 404 Resource not found
ALREADY_EXISTS 409 Resource already exists
RESOURCE_EXHAUSTED 429 Rate limit exceeded
INTERNAL 500 Internal server error
UNAVAILABLE 503 Service unavailable

Error Details#

typescript
import { Status, Metadata } from '@grpc/grpc-js';

client.getStream(request, metadata, (err, response) => {
  if (err) {
    console.error('Code:', err.code);
    console.error('Message:', err.message);
    console.error('Details:', err.metadata?.get('error-details'));
  }
});

Client Examples#

Node.js Client#

typescript
import { StreamServiceClient } from '@aphrodite/proto/stream';
import { credentials, Metadata } from '@grpc/grpc-js';

const client = new StreamServiceClient(
  'stream.aphrodite.example.com:50051',
  credentials.createSsl()
);

// Get stream
const request = { streamId: 'str_abc123' };
const metadata = new Metadata();
metadata.set('authorization', `Bearer ${token}`);

client.getStream(request, metadata, (err, response) => {
  if (err) {
    console.error('Error:', err);
    return;
  }
  console.log('Stream:', response.stream);
});

// Subscribe to events (streaming)
const eventStream = client.subscribeToEvents(
  {
    streamIds: ['str_abc123'],
    eventTypes: ['tip_received', 'goal_completed'],
  },
  metadata
);

eventStream.on('data', (event) => {
  console.log('Event:', event.type, event.payload);
});

eventStream.on('error', (err) => {
  console.error('Stream error:', err);
});

eventStream.on('end', () => {
  console.log('Stream ended');
});

Go Client#

go
package main

import (
    "context"
    "log"

    pb "github.com/aphrodite/proto/stream"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

func main() {
    creds, err := credentials.NewClientTLSFromFile("ca.crt", "")
    if err != nil {
        log.Fatal(err)
    }

    conn, err := grpc.Dial(
        "stream.aphrodite.example.com:50051",
        grpc.WithTransportCredentials(creds),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    client := pb.NewStreamServiceClient(conn)

    ctx := metadata.AppendToOutgoingContext(
        context.Background(),
        "authorization", "Bearer "+token,
    )

    resp, err := client.GetStream(ctx, &pb.GetStreamRequest{
        StreamId: "str_abc123",
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Stream: %v", resp.Stream)
}

Document History#

Date Version Changes
2026-01-18 1.0.0 Initial Stream gRPC API docs