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#
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 |