Add SIPDialtone enum and deprecate play_dialtone (#1892)

* Add SIPDialtone enum and deprecate play_dialtone

Lets callers pick a regional dial tone preset on CreateSIPParticipant
and TransferSIPParticipant. play_dialtone still maps to the ETSI tone
when the enum is unset, and is kept populated for older sip services.

* generated protobuf

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: dennwc

.changeset/sip-dialtone-preset.md

@@ -0,0 +1,6 @@
+---
+"github.com/livekit/protocol": patch
+"@livekit/protocol": patch
+---
+
+Add `SIPDialtone` to select a regional dial tone on CreateSIPParticipant and TransferSIPParticipant; deprecate `play_dialtone`

livekit/livekit_sip.pb.go

@@ -1325,6 +1325,22 @@ func (p *CreateSIPParticipantRequest) Upgrade() {
 		return
 	}
 	p.Media = p.Media.UpgradeWith(p.MediaEncryption)
+	p.Dialtone = UpgradeSIPDialtone(p.Dialtone, p.PlayRingtone || p.PlayDialtone)
+}
+
+func (p *TransferSIPParticipantRequest) Upgrade() {
+	if p == nil {
+		return
+	}
+	p.Dialtone = UpgradeSIPDialtone(p.Dialtone, p.PlayDialtone)
+}
+
+// UpgradeSIPDialtone maps the deprecated play_dialtone flag to SIP_DIALTONE_ETSI when dialtone is unset.
+func UpgradeSIPDialtone(tone SIPDialtone, playDialtone bool) SIPDialtone {
+	if tone == SIPDialtone_SIP_DIALTONE_DISABLED && playDialtone {
+		return SIPDialtone_SIP_DIALTONE_ETSI
+	}
+	return tone
 }
 
 func (p *SIPMediaEncryption) Deref() SIPMediaEncryption {

livekit/livekit_sip.twirp.go

@@ -223,6 +223,18 @@ enum SIPMediaEncryption {
   SIP_MEDIA_ENCRYPT_REQUIRE = 2; // require encryption
 }
 
+// Dial tone (ringback) played while a call is being placed or transferred.
+// Receivers treat unknown values as SIP_DIALTONE_ETSI.
+enum SIPDialtone {
+  SIP_DIALTONE_DISABLED = 0; // no tone
+  SIP_DIALTONE_ETSI = 1; // 425 Hz, 1s on / 4s off; the tone play_dialtone used
+  SIP_DIALTONE_AUTO = 2; // pick by the country of the called number, ETSI if unknown
+  SIP_DIALTONE_US = 3; // North America (NANP)
+  SIP_DIALTONE_UK = 4;
+  SIP_DIALTONE_JP = 5;
+  SIP_DIALTONE_AU = 6;
+}
+
 message SIPCodec {
   string name = 1;
   uint32 rate = 2;
@@ -802,9 +814,11 @@ message CreateSIPParticipantRequest {
   // Character 'w' can be used to add a 0.5 sec delay.
   string dtmf = 5;
 
-  // Optionally play dialtone in the room as an audible indicator for existing participants. The `play_ringtone` option is deprectated but has the same effect.
+  // Deprecated: use dialtone. Setting play_dialtone (or play_ringtone) is equivalent to SIP_DIALTONE_ETSI when dialtone is unset.
   bool play_ringtone = 6 [deprecated = true];
-  bool play_dialtone = 13;
+  bool play_dialtone = 13 [deprecated = true];
+  // Optionally play dialtone in the room as an audible indicator for existing participants.
+  SIPDialtone dialtone = 28;
 
   // By default the From value (Phone number) is used for participant name/identity (if not set) and added to attributes.
   // If true, a random value for identity will be used and numbers will be omitted from attributes.
@@ -848,7 +862,7 @@ message CreateSIPParticipantRequest {
     (logger.redact_format) = "<redacted ({{ .Size }} bytes)>"
   ];
   optional Destination destination = 22;
-  // NEXT ID: 28
+  // NEXT ID: 29
 }
 
 message SIPParticipantInfo {
@@ -863,8 +877,10 @@ message TransferSIPParticipantRequest {
   string room_name = 2;
   string transfer_to = 3;
 
-  // Optionally play dialtone to the SIP participant as an audible indicator of being transferred
-  bool play_dialtone = 4;
+  // Deprecated: use dialtone. Setting play_dialtone is equivalent to SIP_DIALTONE_ETSI when dialtone is unset.
+  bool play_dialtone = 4 [deprecated = true];
+  // Optionally play dialtone to the SIP participant as an audible indicator of being transferred.
+  SIPDialtone dialtone = 7;
 
   // Add the following headers to the REFER SIP request.
   map<string, string> headers = 5 [

livekit/sip.go

@@ -103,8 +103,10 @@ message InternalCreateSIPParticipantRequest {
   // Character 'w' can be used to add a 0.5 sec delay.
   string dtmf = 11;
 
+  // Deprecated: set for older sip services, which only read this field. Read dialtone after Upgrade() instead.
+  bool play_dialtone = 12 [deprecated = true];
   // Optionally play dialtone in the room as an audible indicator for existing participants
-  bool play_dialtone = 12;
+  livekit.SIPDialtone dialtone = 41;
 
   map<string, string> headers = 21 [
     (logger.sensitivity) = SENSITIVITY_PII,
@@ -157,7 +159,7 @@ message InternalCreateSIPParticipantRequest {
   // Provider of the caller number, when the call does not use a customer trunk.
   livekit.ProviderInfo provider_info = 40;
 
-  // NEXT ID: 41
+  // NEXT ID: 42
 }
 
 message InternalCreateSIPParticipantResponse {
@@ -170,8 +172,10 @@ message InternalTransferSIPParticipantRequest {
   string sip_call_id = 1 [(logger.name) = "sipCallID"];
   string transfer_to = 2;
 
+  // Deprecated: set for older sip services, which only read this field. Read dialtone after Upgrade() instead.
+  bool play_dialtone = 3 [deprecated = true];
   // Optionally play dialtone to the SIP participant as an audible indicator of being transferred
-  bool play_dialtone = 3;
+  livekit.SIPDialtone dialtone = 7;
 
   // Add the following headers to the REFER SIP request.
   map<string, string> headers = 4 [

protobufs/livekit_sip.proto

@@ -207,7 +207,8 @@ func NewCreateSIPParticipantRequestResult(
 		ParticipantMetadata:   req.ParticipantMetadata,
 		ParticipantAttributes: attrs,
 		Dtmf:                  req.Dtmf,
-		PlayDialtone:          req.PlayRingtone || req.PlayDialtone,
+		Dialtone:              req.Dialtone,
+		PlayDialtone:          req.Dialtone != livekit.SIPDialtone_SIP_DIALTONE_DISABLED,
 		Headers:               headers,
 		HeadersToAttributes:   hdrToAttr,
 		AttributesToHeaders:   attrToHdr,
@@ -229,17 +230,27 @@ func NewTransferSIPParticipantRequest(
 	callID string,
 	req *livekit.TransferSIPParticipantRequest,
 ) (*InternalTransferSIPParticipantRequest, error) {
+	req.Upgrade()
 	return &InternalTransferSIPParticipantRequest{
 		SipCallId:      callID,
 		TransferTo:     req.TransferTo,
-		PlayDialtone:   req.PlayDialtone,
+		Dialtone:       req.Dialtone,
+		PlayDialtone:   req.Dialtone != livekit.SIPDialtone_SIP_DIALTONE_DISABLED,
 		Headers:        req.Headers,
 		RingingTimeout: req.RingingTimeout,
 	}, nil
 }
 
 func (p *InternalCreateSIPParticipantRequest) Upgrade() {
 	p.Media = p.Media.UpgradeWith(p.MediaEncryption)
+	p.Dialtone = livekit.UpgradeSIPDialtone(p.Dialtone, p.PlayDialtone)
+}
+
+func (p *InternalTransferSIPParticipantRequest) Upgrade() {
+	if p == nil {
+		return
+	}
+	p.Dialtone = livekit.UpgradeSIPDialtone(p.Dialtone, p.PlayDialtone)
 }
 
 func (p *EvaluateSIPDispatchRulesResponse) Upgrade() {