From dc2f7b366a437db67d2409da61ba0e83380c6cb4 Mon Sep 17 00:00:00 2001
From: Emir Aganovic <emir.aganovic@babelforce.com>
Date: Tue, 17 Sep 2024 21:42:44 +0200
Subject: [PATCH] fix: add more api docs

---
 docs/api_docs/index.html  | 20 +++++++++++++++++++-
 docs/index.xml            | 15 +++++++++------
 docs/why_diago/index.html | 34 +++++-----------------------------
 en.search-data.json       |  2 +-
 4 files changed, 34 insertions(+), 37 deletions(-)

diff --git a/docs/api_docs/index.html b/docs/api_docs/index.html
index ba3eb6e..e749547 100644
--- a/docs/api_docs/index.html
+++ b/docs/api_docs/index.html
@@ -42,7 +42,7 @@
 Dialog Sessions diago can act as UAS(User Agent Server) and UAC(User Agent Client), and adds bridging capability to build B2BUA services.
 It intentionally distincts dialog received (Acting as server) and dialog created (Acting as client):
 DialogServerSession when receving incoming dialog (SIP INVITE) and setups session (media) DialogClientSession when it creates outgoing dialog (SIP INVITE) and setups session (media) For best understanding here some docs with short code reference.">
-  <meta itemprop="wordCount" content="577">
+  <meta itemprop="wordCount" content="639">
   <meta name="twitter:card" content="summary">
   <meta name="twitter:title" content="API Docs">
   <meta name="twitter:description" content="Library API tries to be well documented through comments. For more reference visit GO DOC
@@ -258,6 +258,12 @@
                 class="hx-flex hx-rounded hx-px-2 hx-py-1.5 hx-text-sm hx-transition-colors [word-break:break-word] hx-cursor-pointer [-webkit-tap-highlight-color:transparent] [-webkit-touch-callout:none] contrast-more:hx-border hx-gap-2 before:hx-opacity-25 before:hx-content-['#'] hx-text-gray-500 hover:hx-bg-gray-100 hover:hx-text-gray-900 dark:hx-text-neutral-400 dark:hover:hx-bg-primary-100/5 dark:hover:hx-text-gray-50 contrast-more:hx-text-gray-900 contrast-more:dark:hx-text-gray-50 contrast-more:hx-border-transparent contrast-more:hover:hx-border-gray-900 contrast-more:dark:hover:hx-border-gray-50"
               >Answering call</a>
             </li>
+          <li>
+              <a
+                href="#media-handling"
+                class="hx-flex hx-rounded hx-px-2 hx-py-1.5 hx-text-sm hx-transition-colors [word-break:break-word] hx-cursor-pointer [-webkit-tap-highlight-color:transparent] [-webkit-touch-callout:none] contrast-more:hx-border hx-gap-2 before:hx-opacity-25 before:hx-content-['#'] hx-text-gray-500 hover:hx-bg-gray-100 hover:hx-text-gray-900 dark:hx-text-neutral-400 dark:hover:hx-bg-primary-100/5 dark:hover:hx-text-gray-50 contrast-more:hx-text-gray-900 contrast-more:dark:hx-text-gray-50 contrast-more:hx-border-transparent contrast-more:hover:hx-border-gray-900 contrast-more:dark:hover:hx-border-gray-50"
+              >Media handling</a>
+            </li>
           <li>
               <a
                 href="#playback"
@@ -383,6 +389,10 @@
         <a class="hx-font-semibold hx-inline-block hx-text-gray-500 hover:hx-text-gray-900 dark:hx-text-gray-400 dark:hover:hx-text-gray-300 contrast-more:hx-text-gray-900 contrast-more:hx-underline contrast-more:dark:hx-text-gray-50 hx-w-full hx-break-words" href="#answering-call">Answering call
         </a>
       </li>
+      <li class="hx-my-2 hx-scroll-my-6 hx-scroll-py-6">
+        <a class="hx-font-semibold hx-inline-block hx-text-gray-500 hover:hx-text-gray-900 dark:hx-text-gray-400 dark:hover:hx-text-gray-300 contrast-more:hx-text-gray-900 contrast-more:hx-underline contrast-more:dark:hx-text-gray-50 hx-w-full hx-break-words" href="#media-handling">Media handling
+        </a>
+      </li>
       <li class="hx-my-2 hx-scroll-my-6 hx-scroll-py-6">
         <a class="hx-font-semibold hx-inline-block hx-text-gray-500 hover:hx-text-gray-900 dark:hx-text-gray-400 dark:hover:hx-text-gray-300 contrast-more:hx-text-gray-900 contrast-more:hx-underline contrast-more:dark:hx-text-gray-50 hx-w-full hx-break-words" href="#playback">Playback
         </a>
@@ -570,6 +580,14 @@ <h2>Answering call<span class="hx-absolute -hx-mt-20" id="answering-call"></span
 
   
 </div>
+<h2>Media handling<span class="hx-absolute -hx-mt-20" id="media-handling"></span>
+    <a href="#media-handling" class="subheading-anchor" aria-label="Permalink for this section"></a></h2><p>Every session comes with 2 streams (Audio for now). In diago case it is referenced as reader/writer.</p>
+<ul>
+<li><code>AudioReader</code> reads incoming stream</li>
+<li><code>AudioWriter</code> writes outgoing stream</li>
+</ul>
+<p>Normally you mostly deal with writing audio so <strong>Playback</strong> is created for easier dealing with audio streams.</p>
+<p><strong>NOTE</strong>: Diago does not automatically reads audio stream in background. This can happen with explicit call or <em>bridging</em>.</p>
 <h2>Playback<span class="hx-absolute -hx-mt-20" id="playback"></span>
     <a href="#playback" class="subheading-anchor" aria-label="Permalink for this section"></a></h2><p>Playing audio file is done with audio playback. Library provides prebuilt playback functionality</p>
 <p>Playback can:</p>
diff --git a/docs/index.xml b/docs/index.xml
index 9193c41..c18a7a7 100644
--- a/docs/index.xml
+++ b/docs/index.xml
@@ -294,6 +294,14 @@ Dialog created is scoped (Like HTTP request serving). Once dialog exists, it is
 
   
 &lt;/div&gt;
+&lt;h2&gt;Media handling&lt;span class=&#34;hx-absolute -hx-mt-20&#34; id=&#34;media-handling&#34;&gt;&lt;/span&gt;
+    &lt;a href=&#34;#media-handling&#34; class=&#34;subheading-anchor&#34; aria-label=&#34;Permalink for this section&#34;&gt;&lt;/a&gt;&lt;/h2&gt;&lt;p&gt;Every session comes with 2 streams (Audio for now). In diago case it is referenced as reader/writer.&lt;/p&gt;
+&lt;ul&gt;
+&lt;li&gt;&lt;code&gt;AudioReader&lt;/code&gt; reads incoming stream&lt;/li&gt;
+&lt;li&gt;&lt;code&gt;AudioWriter&lt;/code&gt; writes outgoing stream&lt;/li&gt;
+&lt;/ul&gt;
+&lt;p&gt;Normally you mostly deal with writing audio so &lt;strong&gt;Playback&lt;/strong&gt; is created for easier dealing with audio streams.&lt;/p&gt;
+&lt;p&gt;&lt;strong&gt;NOTE&lt;/strong&gt;: Diago does not automatically reads audio stream in background. This can happen with explicit call or &lt;em&gt;bridging&lt;/em&gt;.&lt;/p&gt;
 &lt;h2&gt;Playback&lt;span class=&#34;hx-absolute -hx-mt-20&#34; id=&#34;playback&#34;&gt;&lt;/span&gt;
     &lt;a href=&#34;#playback&#34; class=&#34;subheading-anchor&#34; aria-label=&#34;Permalink for this section&#34;&gt;&lt;/a&gt;&lt;/h2&gt;&lt;p&gt;Playing audio file is done with audio playback. Library provides prebuilt playback functionality&lt;/p&gt;
 &lt;p&gt;Playback can:&lt;/p&gt;
@@ -514,12 +522,7 @@ Publishing local IP like above is problem for NAT and there different approaches
       <description>
         
         
-        &lt;h2&gt;Why Diago?&lt;span class=&#34;hx-absolute -hx-mt-20&#34; id=&#34;why-diago&#34;&gt;&lt;/span&gt;
-    &lt;a href=&#34;#why-diago&#34; class=&#34;subheading-anchor&#34; aria-label=&#34;Permalink for this section&#34;&gt;&lt;/a&gt;&lt;/h2&gt;&lt;p&gt;Development of VOIP services can be slow or it was full workarrounds.
-Diago try to offer more modern Stack and put you closer to protcol,network,media but offering High level and low level API calls.&lt;/p&gt;
-&lt;p&gt;Diago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance.&lt;/p&gt;
-&lt;p&gt;In case you wondering is Go right language, there are already good benchmark results with just &lt;a href=&#34;https://github.com/emiago/sipgo&#34; target=&#34;_blank&#34; rel=&#34;noopener&#34;&gt;sipgo&lt;/a&gt;.&lt;/p&gt;
-
+        
       </description>
     </item>
     
diff --git a/docs/why_diago/index.html b/docs/why_diago/index.html
index 6877a9d..5be7030 100644
--- a/docs/why_diago/index.html
+++ b/docs/why_diago/index.html
@@ -12,8 +12,7 @@
 <link fetchpriority="low" href="/diago/site.webmanifest" rel="manifest" />
 
   <title>Diago</title>
-  <meta name="description" content="Why Diago? Development of VOIP services can be slow or it was full workarrounds. Diago try to offer more modern Stack and put you closer to protcol,network,media but offering High level and low level API calls.
-Diago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance." />
+  <meta name="description" content="" />
 
   
     <link rel="canonical" href="https://emiago.github.io/diago/docs/why_diago/" itemprop="url" />
@@ -22,8 +21,7 @@
   
 
 <meta property="og:title" content="" />
-<meta property="og:description" content="Why Diago? Development of VOIP services can be slow or it was full workarrounds. Diago try to offer more modern Stack and put you closer to protcol,network,media but offering High level and low level API calls.
-Diago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance." />
+<meta property="og:description" content="" />
 <meta property="og:type" content="article" />
 <meta property="og:url" content="https://emiago.github.io/diago/docs/why_diago/" /><meta property="article:section" content="docs" />
 
@@ -31,13 +29,8 @@
 
   
   <meta itemprop="name" content="Diago">
-  <meta itemprop="description" content="Why Diago? Development of VOIP services can be slow or it was full workarrounds. Diago try to offer more modern Stack and put you closer to protcol,network,media but offering High level and low level API calls.
-Diago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance.">
-  <meta itemprop="wordCount" content="94">
   <meta name="twitter:card" content="summary">
   <meta name="twitter:title" content="Diago">
-  <meta name="twitter:description" content="Why Diago? Development of VOIP services can be slow or it was full workarrounds. Diago try to offer more modern Stack and put you closer to protcol,network,media but offering High level and low level API calls.
-Diago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance.">
 
     <link rel="preload" href="/diago/css/compiled/main.min.c1fe2c80102c9dc9ddc66184191e646769052d36a21b38ac5ab5077713cf7a81.css" as="style" integrity="sha256-wf4sgBAsncndxmGEGR5kZ2kFLTaiGzisWrUHdxPPeoE=" />
     <link href="/diago/css/compiled/main.min.c1fe2c80102c9dc9ddc66184191e646769052d36a21b38ac5ab5077713cf7a81.css" rel="stylesheet" integrity="sha256-wf4sgBAsncndxmGEGR5kZ2kFLTaiGzisWrUHdxPPeoE=" />
@@ -224,14 +217,6 @@
   >Why Diago
     </a>
   
-    <ul class='hx-flex hx-flex-col hx-gap-1 hx-relative before:hx-absolute before:hx-inset-y-1 before:hx-w-px before:hx-bg-gray-200 before:hx-content-[""] dark:before:hx-bg-neutral-800 ltr:hx-pl-3 ltr:before:hx-left-0 rtl:hx-pr-3 rtl:before:hx-right-0 ltr:hx-ml-3 rtl:hx-mr-3'><li>
-              <a
-                href="#why-diago"
-                class="hx-flex hx-rounded hx-px-2 hx-py-1.5 hx-text-sm hx-transition-colors [word-break:break-word] hx-cursor-pointer [-webkit-tap-highlight-color:transparent] [-webkit-touch-callout:none] contrast-more:hx-border hx-gap-2 before:hx-opacity-25 before:hx-content-['#'] hx-text-gray-500 hover:hx-bg-gray-100 hover:hx-text-gray-900 dark:hx-text-neutral-400 dark:hover:hx-bg-primary-100/5 dark:hover:hx-text-gray-50 contrast-more:hx-text-gray-900 contrast-more:dark:hx-text-gray-50 contrast-more:hx-border-transparent contrast-more:hover:hx-border-gray-900 contrast-more:dark:hover:hx-border-gray-50"
-              >Why Diago?</a>
-            </li>
-          </ul>
-  
               
             </li></ul>
       </div></li>
@@ -310,12 +295,8 @@
 </div></div></aside>
     
 <nav class="hextra-toc hx-order-last hx-hidden hx-w-64 hx-shrink-0 xl:hx-block print:hx-hidden hx-px-4" aria-label="table of contents">
-    <div class="hextra-scrollbar hx-sticky hx-top-16 hx-overflow-y-auto hx-pr-4 hx-pt-6 hx-text-sm [hyphens:auto] hx-max-h-[calc(100vh-var(--navbar-height)-env(safe-area-inset-bottom))] ltr:hx--mr-4 rtl:hx--ml-4"><p class="hx-mb-4 hx-font-semibold hx-tracking-tight">On this page</p><ul>
-      <li class="hx-my-2 hx-scroll-my-6 hx-scroll-py-6">
-        <a class="hx-font-semibold hx-inline-block hx-text-gray-500 hover:hx-text-gray-900 dark:hx-text-gray-400 dark:hover:hx-text-gray-300 contrast-more:hx-text-gray-900 contrast-more:hx-underline contrast-more:dark:hx-text-gray-50 hx-w-full hx-break-words" href="#why-diago">Why Diago?
-        </a>
-      </li></ul>
-      <div class="hx-mt-8 hx-border-t hx-bg-white hx-pt-8 hx-shadow-[0_-12px_16px_white] dark:hx-bg-dark dark:hx-shadow-[0_-12px_16px_#111] hx-sticky hx-bottom-0 hx-flex hx-flex-col hx-items-start hx-gap-2 hx-pb-8 dark:hx-border-neutral-800 contrast-more:hx-border-t contrast-more:hx-border-neutral-400 contrast-more:hx-shadow-none contrast-more:dark:hx-border-neutral-400">
+    <div class="hextra-scrollbar hx-sticky hx-top-16 hx-overflow-y-auto hx-pr-4 hx-pt-6 hx-text-sm [hyphens:auto] hx-max-h-[calc(100vh-var(--navbar-height)-env(safe-area-inset-bottom))] ltr:hx--mr-4 rtl:hx--ml-4">
+      <div class=" hx-sticky hx-bottom-0 hx-flex hx-flex-col hx-items-start hx-gap-2 hx-pb-8 dark:hx-border-neutral-800 contrast-more:hx-border-t contrast-more:hx-border-neutral-400 contrast-more:hx-shadow-none contrast-more:dark:hx-border-neutral-400">
         <button aria-hidden="true" id="backToTop" onClick="scrollUp();" class="hx-transition-all hx-duration-75 hx-opacity-0 hx-text-xs hx-font-medium hx-text-gray-500 hover:hx-text-gray-900 dark:hx-text-gray-400 dark:hover:hx-text-gray-100 contrast-more:hx-text-gray-800 contrast-more:dark:hx-text-gray-50">
           <span>Scroll to top</span>
           <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="hx-inline ltr:hx-ml-1 rtl:hx-mr-1 hx-h-3.5 hx-w-3.5 hx-border hx-rounded-full hx-border-gray-500 hover:hx-border-gray-900 dark:hx-border-gray-400 dark:hover:hx-border-gray-100 contrast-more:hx-border-gray-800 contrast-more:dark:hx-border-gray-50">
@@ -338,12 +319,7 @@
 
         <div class="content">
           <h1></h1>
-          <h2>Why Diago?<span class="hx-absolute -hx-mt-20" id="why-diago"></span>
-    <a href="#why-diago" class="subheading-anchor" aria-label="Permalink for this section"></a></h2><p>Development of VOIP services can be slow or it was full workarrounds.
-Diago try to offer more modern Stack and put you closer to protcol,network,media but offering High level and low level API calls.</p>
-<p>Diago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance.</p>
-<p>In case you wondering is Go right language, there are already good benchmark results with just <a href="https://github.com/emiago/sipgo" target="_blank" rel="noopener">sipgo</a>.</p>
-
+          
         </div>
         <div class="hx-mt-16"></div>
         <div class="hx-mb-8 hx-flex hx-items-center hx-border-t hx-pt-8 dark:hx-border-neutral-800 contrast-more:hx-border-neutral-400 dark:contrast-more:hx-border-neutral-400 print:hx-hidden"><a
diff --git a/en.search-data.json b/en.search-data.json
index 12a45e9..ccbcd74 100644
--- a/en.search-data.json
+++ b/en.search-data.json
@@ -1 +1 @@
-{"/diago/docs/":{"data":{"":"","core-roadmap#Core (Roadmap):":"","diagox#diagox":"Welcome to diago documentation!.\nWhat is Diago for? If you are familiar with terms Calling, Bridging, Conferencing, IVR, Recording, Transcribing, Voicemail … that is all about.\nDeveloping this kind of services can be challenging when it needs more behavior, monitoring, integrations etc…\nDiago with GO offers faster way of developing and testing communication services, but with keeping care on still providing low latency.\nMore on Why Diago\nCore (Roadmap): WIP = Work in progress (Expect soon to be part of lib)\nFull dialog control and High Level API alaw,ulaw codecs (opus as third is planned as well) Audio package for streaming: WAV reader/writer, PCM transcoding to alaw/ulaw Playbacks as buffers,files(wav),url Playback URL streaming Playback with control mute/unmute Audio Reader/Writer stream exposed for manual processing like sending to third party DTMF with RTP Handling Reinvites with media updates Bridging as proxy media for 2 parties B2BUA Handling transfers (Refers) (WIP) Conferencing audio DTMF with SIP INFO (Needed more in case webrtc) Writing Unit Test on Server with SIP and Media Recorder (WIP) RTP symetric SRTP for more critical services And plenty more … diagox Diago extra modules\nSome of modules are not yet considered to be part of lib and they are developed for private projects. To mention few:\nRecording Webrtc(pion) stack over diago’s media stack Complex modules etc… If you have interest or need consulting/sponsoring please contact me on mail","what-is-diago-for#What is Diago for?":"","why-diago#Why Diago?":"Development of VOIP services can be slow or it was full workarrounds. Diago try to offer more modern Stack and put you closer to protocol,network,media but offering High level and low level API calls.\nDiago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance.\nIn case you wondering is Go right language, there are already good benchmark results with just sipgo proxysip benchmarks.\nNEXT: -\u003e Guides"},"title":"_index"},"/diago/docs/api_docs/":{"data":{"":"Library API tries to be well documented through comments. For more reference visit GO DOC\nHere we explain some of main built in concepts and usage.","answering-call#Answering call":" func Answer(inDialog *diago.DialogServerSession) { inDialog.Progress() // Progress -\u003e 100 Trying inDialog.Ringing() // Ringing -\u003e 180 Response if err := inDialog.Answer(); err != nil { fmt.Println(\"Failed to answer\", err) return } ctx := inDialog.Context() select { case \u003c-ctx.Done(): case \u003c-time.After(1 * time.Minute): } } ","bridge#Bridge":"Bridge allows bridging your Dialog Sessions. If dialogs are answered and have media sessions you can bridge them.\nbridge := diago.NewBridge() bridge.AddDialogSession(d1) bridge.AddDialogSession(d2) For now bridge is only doing proxy of RTP and it does not allow Transcoding.\nTranscoding is generally something you do not want in running system so bridge will return error in case codecs are missmatch.","dialog-sessions#Dialog Sessions":"diago can act as UAS(User Agent Server) and UAC(User Agent Client), and adds bridging capability to build B2BUA services.\nIt intentionally distincts dialog received (Acting as server) and dialog created (Acting as client):\nDialogServerSession when receving incoming dialog (SIP INVITE) and setups session (media) DialogClientSession when it creates outgoing dialog (SIP INVITE) and setups session (media) For best understanding here some docs with short code reference.","incoming-call#Incoming call":"Calling Serve allows to serve every new call. Here you can build you routing by accessing dialog. Some of helpers are added\nToUser - destination callerID FromUser - from callerID Transport - transport of SIP message See example below.\ndg.Serve(ctx, func(inDialog *diago.DialogServerSession) { // - Do your call routing. switch inDialog.ToUser() { case \"answer\": case \"123456\" } // inDialog is scope limited, exiting this routine will Close dialog. // Use Context to hold dialog in routine \u003c-inDialog.Context().Done() }) NOTE: Dialog created is scoped (Like HTTP request serving). Once dialog exists, it is cleaned up, so no further action is needed.","outgoing-call#Outgoing call":"Invite sends SIP INVITE and waits for answer. After succesfull answer you can apply many other actions for dialog.\ndialog, err := dg.Invite(ctx, recipient sip.Uri, opts diago.InviteOptions) if err != nil { // Handle err. Special ErrDialogResponse is returned if non 200 is received } defer dialog.Close() // Closing outgoing dialog is needed // Do something // Hangup dialog.Hangup() ","playback#Playback":"Playing audio file is done with audio playback. Library provides prebuilt playback functionality\nPlayback can:\nPlay File (wav/PCM) Play any stream (no encoders) Either outgoing or incoming after leg is answered you can create playback\npb, err := dialog.PlaybackCreate() if err != nil { fmt.Println(\"Failed to create playback\", err) return } if err := pb.Play(playfile, \"audio/wav\"); err != nil { fmt.Println(\"Playing failed\", err) } } Playback with control If you need to control your playback like Mute Unmute or just to Stop current playback, then you can use AudioPlaybackControl\npb, err := dialog.PlaybackControlCreate() if err != nil { fmt.Println(\"Failed to create playback\", err) return } go pb.Play(playfile, \"audio/wav\") // Note needs error handling pb.Mute(true) // Mute/Unmute audio pb.Stop() // Stop playing audio. This will make Play exit } ","setup#Setup":"Diago needs instance to be created NewDiago or in other words instance represents single UserAgent.\nWith this instance you can serve multiple incoming dialogs or dial destinations in parallel.\nua, _ := sipgo.NewUA() dg := diago.NewDiago(ua) Customize SIP Transport Diago allows you to customize transport listeners with WithTransport Below example makes diago only listen for TCP SIP.\ntransportTCP := diago.Transport{ Transport: \"tcp\", BindHost: \"127.0.0.1\", BindPort: 5060, } dg := diago.NewDiago(ua, diago.WithTransport(transportTCP), ) Transport support: UDP, TCP, TLS, WS, WSS\nFor more configuration checkout GO Docs"},"title":"API Docs"},"/diago/docs/examples/":{"data":{"":"","audio-playback#Audio playback":" ","audio-playback-with-control#Audio playback with control":" ","cli-softphone-for-testing#CLI Softphone for testing":"For testing below scenarios, gophone as CLI softphone is used, but you can use any softphone you like.\nVisit the page and install: https://github.com/emiago/gophone\nSource code of examples is in library. You will need go compiler installed.\nHere we show couple of them","dtmf#DTMF":" "},"title":"Demo     Examples"},"/diago/docs/getting_started/":{"data":{"":"","echo-test-app#Echo test app":"Copy audio file from library testdata/files/demo-echotest.wav or change to whatever you want\nua, _ := sipgo.NewUA() dg := diago.NewDiago(ua) dg.Serve(ctx, func(inDialog *diago.DialogServerSession) { inDialog.Progress() // Progress -\u003e 100 Trying inDialog.Answer(); // Answer // Make sure file below exists in work dir playfile, err := os.Open(\"demo-echotest.wav\") if err != nil { fmt.Println(\"Failed to open file\", err) return } defer playfile.Close() // Create playback and play file. pb, _ := inDialog.PlaybackCreate() if err := pb.Play(playfile, \"audio/wav\"); err != nil { fmt.Println(\"Playing failed\", err) } } Dial in with softphone on 127.0.0.1:5060 and you should here audio playing.\nWith gophone:\ngophone dial -media=speaker sip:111@127.0.0.1 ","getting-started#Getting started":"As showcase, code below is only needed to start serving Calls. In this example Call will be answered and played some audio.\nFor testing you can use gophone CLI sofpthone built with same libraries or any other SIP softphone."},"title":"getting_started"},"/diago/docs/guides/":{"data":{"":"Understanding VOIP can be a challenge for newcomers, but can it be simple and easier approach?\nVOIP is now mostly built with SIP. SIP is textual protocol same as HTTP so if you know HTTP reading SIP messages will be easy. It acts similar and has similar behavior (request/response) but focus is more on Session. With realtime media like audio/video there is always session after which it ends. Creating, Updating, Clossing this Session is something that SIP is designed\nTo understand and have good debug skills it is important to know how SIP works in different situations. Here I will try to provide some simple documentation to help you BUILDERS.\nNext: Understanding SIP with Call Scenarios"},"title":"Guides"},"/diago/docs/guides/sip_and_media/":{"data":{"":"","undestanding-sip-and-media#Undestanding SIP and media":"INVITE carries SDP (application/sdp) in body of message as offer to explain media capabilites and connection setup. INVITE can have any other type in Body like HTTP, but SDP protocol is mainly used. More about this later.\nAccepting(Answering) call is done by respondin with 200 OK\nResponse carries SDP in body as answer to explain callee’s media capabilites and connection.\nCall with media With SDP we explain our capabilites and protocol used for media and this mostly boils down to this 3 things:\nexplaining which codecs are supported for decoding (alaw,ulaw, opus, g722, …), protocol and profile (RTP AVP). RTP can have different profile but AVP (Audio Video) is used in this case and Listen IP where we expect incoming media (UDP) Returning 200 For realtime media RTP is one mostly used. Anyway in case Bob has no similar capabilities, lets say codecs, Bob will send non 200 response and call will be terminated.\nSending ACK After Caller receiving 200 OK it is required that Caller acknowledge Callee capabilities, by sending ACK (non transactional, no response) request.\nCodecs Codecs or in other words Formats are identified as numbers. There are static defined by AVP profile or user can have any other defined with own custom numbers. In above case we use statically defined.\n0 ulaw 8000Hz 8 alaw 8000Hz In SDP this will be shown as m=desc key. Ex:\nm=audio 49170 RTP/AVP 0 8\nDescription:\naudio: type of stream 49170: port on which is listening RTP/AVP: identifier for RTP protocol and AVP denotes as Audio Video 0: is codec identifier Normally this should be followed with a=rtpmap attributes to explain about codecs. In case static this is not required.\nListen IP Information and where device/use is listening for incoming media traffic c=IN IP4 198.51.100.1\nIP4 denotes IP version 4 is used With nowdays NAT this unfortunatelly makes problem, as you can expect end user behind NAT will publish his private IP like 192.168.1.1. This is solved in different ways, but for now we will stop here. Other problem is if call is jumping between media servers, above can be changed with new IP received via new INVITE messaging.\nNOTE: Publishing local IP like above is problem for NAT and there different approaches to solve this issue, but for now we will skip this part."},"title":"SIP and Media"},"/diago/docs/guides/understanding_sip/":{"data":{"":"","#":"Every call starts with INVITE SIP Messages. Here is how to relate SIP message to PHONE actions\nDialing = INVITE Answer = 200 OK response on INVITE Hangup = BYE Cancel = CANCEL Reject = 486 Busy INVITE is creating session which we call dialog.\nCaller (Client): Sends one time ACK as confirmation\nSuccesfull call Example of alice inviting bob\nINVITE sip:bob@127.0.0.1:5060 SIP/2.0 Via: SIP/2.0/udp 127.0.0.99:50725;branch=z9hG4bK.pgb382qZ312tyXIP Content-Type: application/sdp Content-Length: 235 Contact: \u003csip:alice@127.0.0.99:50725\u003e;transport=udp From: \"alice\" \u003csip:alice@127.0.0.99\u003e;tag=hImscoj6Jew8y6da To: \u003csip:bob@127.0.0.1\u003e Call-ID: 729cd7dd-96dc-419b-b339-327c60dfc2d7 CSeq: 1 INVITE Max-Forwards: 70 Succesfull call with provisional responses (More realistic) Call establishment can take a while, so provisional responses help with this.\nProvisional responses = 1xx and mostly you will see 100 and 180. 100 is used in HTTP as well, it just notifies client that request is accepted but it is in progress.\nAfter very quickly you may have Ringing, which indicates that end user device is reached and it is ringing.\nCanceling call with SIP CANCEL Caller cancels call by sending CANCEL msg. It must contain same headers as INVITE for matching transcaction.\nCANCEL is new transaction request like INVITE which receives response, but SIP uses this request to try match existing INVITE transaction. That is why 200 OK is replied\nOnce Bob finds matching transcation it terminates and sends respond to INVITE with 487 Request terminated\nTO BE CONTINUED"},"title":"Understading SIP with Call Scenarios"},"/diago/docs/why_diago/":{"data":{"":"","why-diago#Why Diago?":"Why Diago? Development of VOIP services can be slow or it was full workarrounds. Diago try to offer more modern Stack and put you closer to protcol,network,media but offering High level and low level API calls.\nDiago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance.\nIn case you wondering is Go right language, there are already good benchmark results with just sipgo."},"title":"why_diago"}}
\ No newline at end of file
+{"/diago/docs/":{"data":{"":"","core-roadmap#Core (Roadmap):":"","diagox#diagox":"Welcome to diago documentation!.\nWhat is Diago for? If you are familiar with terms Calling, Bridging, Conferencing, IVR, Recording, Transcribing, Voicemail … that is all about.\nDeveloping this kind of services can be challenging when it needs more behavior, monitoring, integrations etc…\nDiago with GO offers faster way of developing and testing communication services, but with keeping care on still providing low latency.\nMore on Why Diago\nCore (Roadmap): WIP = Work in progress (Expect soon to be part of lib)\nFull dialog control and High Level API alaw,ulaw codecs (opus as third is planned as well) Audio package for streaming: WAV reader/writer, PCM transcoding to alaw/ulaw Playbacks as buffers,files(wav),url Playback URL streaming Playback with control mute/unmute Audio Reader/Writer stream exposed for manual processing like sending to third party DTMF with RTP Handling Reinvites with media updates Bridging as proxy media for 2 parties B2BUA Handling transfers (Refers) (WIP) Conferencing audio DTMF with SIP INFO (Needed more in case webrtc) Writing Unit Test on Server with SIP and Media Recorder (WIP) RTP symetric SRTP for more critical services And plenty more … diagox Diago extra modules\nSome of modules are not yet considered to be part of lib and they are developed for private projects. To mention few:\nRecording Webrtc(pion) stack over diago’s media stack Complex modules etc… If you have interest or need consulting/sponsoring please contact me on mail","what-is-diago-for#What is Diago for?":"","why-diago#Why Diago?":"Development of VOIP services can be slow or it was full workarrounds. Diago try to offer more modern Stack and put you closer to protocol,network,media but offering High level and low level API calls.\nDiago is built with GO language and we are keeping well optimized sip and media stack to have performance and low GC latency. Major win is Go offers fast development speed and memory safety, but also tooling to tweak best performance.\nIn case you wondering is Go right language, there are already good benchmark results with just sipgo proxysip benchmarks.\nNEXT: -\u003e Guides"},"title":"_index"},"/diago/docs/api_docs/":{"data":{"":"Library API tries to be well documented through comments. For more reference visit GO DOC\nHere we explain some of main built in concepts and usage.","answering-call#Answering call":" func Answer(inDialog *diago.DialogServerSession) { inDialog.Progress() // Progress -\u003e 100 Trying inDialog.Ringing() // Ringing -\u003e 180 Response if err := inDialog.Answer(); err != nil { fmt.Println(\"Failed to answer\", err) return } ctx := inDialog.Context() select { case \u003c-ctx.Done(): case \u003c-time.After(1 * time.Minute): } } ","bridge#Bridge":"Bridge allows bridging your Dialog Sessions. If dialogs are answered and have media sessions you can bridge them.\nbridge := diago.NewBridge() bridge.AddDialogSession(d1) bridge.AddDialogSession(d2) For now bridge is only doing proxy of RTP and it does not allow Transcoding.\nTranscoding is generally something you do not want in running system so bridge will return error in case codecs are missmatch.","dialog-sessions#Dialog Sessions":"diago can act as UAS(User Agent Server) and UAC(User Agent Client), and adds bridging capability to build B2BUA services.\nIt intentionally distincts dialog received (Acting as server) and dialog created (Acting as client):\nDialogServerSession when receving incoming dialog (SIP INVITE) and setups session (media) DialogClientSession when it creates outgoing dialog (SIP INVITE) and setups session (media) For best understanding here some docs with short code reference.","incoming-call#Incoming call":"Calling Serve allows to serve every new call. Here you can build you routing by accessing dialog. Some of helpers are added\nToUser - destination callerID FromUser - from callerID Transport - transport of SIP message See example below.\ndg.Serve(ctx, func(inDialog *diago.DialogServerSession) { // - Do your call routing. switch inDialog.ToUser() { case \"answer\": case \"123456\" } // inDialog is scope limited, exiting this routine will Close dialog. // Use Context to hold dialog in routine \u003c-inDialog.Context().Done() }) NOTE: Dialog created is scoped (Like HTTP request serving). Once dialog exists, it is cleaned up, so no further action is needed.","media-handling#Media handling":"Every session comes with 2 streams (Audio for now). In diago case it is referenced as reader/writer.\nAudioReader reads incoming stream AudioWriter writes outgoing stream Normally you mostly deal with writing audio so Playback is created for easier dealing with audio streams.\nNOTE: Diago does not automatically reads audio stream in background. This can happen with explicit call or bridging.","outgoing-call#Outgoing call":"Invite sends SIP INVITE and waits for answer. After succesfull answer you can apply many other actions for dialog.\ndialog, err := dg.Invite(ctx, recipient sip.Uri, opts diago.InviteOptions) if err != nil { // Handle err. Special ErrDialogResponse is returned if non 200 is received } defer dialog.Close() // Closing outgoing dialog is needed // Do something // Hangup dialog.Hangup() ","playback#Playback":"Playing audio file is done with audio playback. Library provides prebuilt playback functionality\nPlayback can:\nPlay File (wav/PCM) Play any stream (no encoders) Either outgoing or incoming after leg is answered you can create playback\npb, err := dialog.PlaybackCreate() if err != nil { fmt.Println(\"Failed to create playback\", err) return } if err := pb.Play(playfile, \"audio/wav\"); err != nil { fmt.Println(\"Playing failed\", err) } } Playback with control If you need to control your playback like Mute Unmute or just to Stop current playback, then you can use AudioPlaybackControl\npb, err := dialog.PlaybackControlCreate() if err != nil { fmt.Println(\"Failed to create playback\", err) return } go pb.Play(playfile, \"audio/wav\") // Note needs error handling pb.Mute(true) // Mute/Unmute audio pb.Stop() // Stop playing audio. This will make Play exit } ","setup#Setup":"Diago needs instance to be created NewDiago or in other words instance represents single UserAgent.\nWith this instance you can serve multiple incoming dialogs or dial destinations in parallel.\nua, _ := sipgo.NewUA() dg := diago.NewDiago(ua) Customize SIP Transport Diago allows you to customize transport listeners with WithTransport Below example makes diago only listen for TCP SIP.\ntransportTCP := diago.Transport{ Transport: \"tcp\", BindHost: \"127.0.0.1\", BindPort: 5060, } dg := diago.NewDiago(ua, diago.WithTransport(transportTCP), ) Transport support: UDP, TCP, TLS, WS, WSS\nFor more configuration checkout GO Docs"},"title":"API Docs"},"/diago/docs/examples/":{"data":{"":"","audio-playback#Audio playback":" ","audio-playback-with-control#Audio playback with control":" ","cli-softphone-for-testing#CLI Softphone for testing":"For testing below scenarios, gophone as CLI softphone is used, but you can use any softphone you like.\nVisit the page and install: https://github.com/emiago/gophone\nSource code of examples is in library. You will need go compiler installed.\nHere we show couple of them","dtmf#DTMF":" "},"title":"Demo     Examples"},"/diago/docs/getting_started/":{"data":{"":"","echo-test-app#Echo test app":"Copy audio file from library testdata/files/demo-echotest.wav or change to whatever you want\nua, _ := sipgo.NewUA() dg := diago.NewDiago(ua) dg.Serve(ctx, func(inDialog *diago.DialogServerSession) { inDialog.Progress() // Progress -\u003e 100 Trying inDialog.Answer(); // Answer // Make sure file below exists in work dir playfile, err := os.Open(\"demo-echotest.wav\") if err != nil { fmt.Println(\"Failed to open file\", err) return } defer playfile.Close() // Create playback and play file. pb, _ := inDialog.PlaybackCreate() if err := pb.Play(playfile, \"audio/wav\"); err != nil { fmt.Println(\"Playing failed\", err) } } Dial in with softphone on 127.0.0.1:5060 and you should here audio playing.\nWith gophone:\ngophone dial -media=speaker sip:111@127.0.0.1 ","getting-started#Getting started":"As showcase, code below is only needed to start serving Calls. In this example Call will be answered and played some audio.\nFor testing you can use gophone CLI sofpthone built with same libraries or any other SIP softphone."},"title":"getting_started"},"/diago/docs/guides/":{"data":{"":"Understanding VOIP can be a challenge for newcomers, but can it be simple and easier approach?\nVOIP is now mostly built with SIP. SIP is textual protocol same as HTTP so if you know HTTP reading SIP messages will be easy. It acts similar and has similar behavior (request/response) but focus is more on Session. With realtime media like audio/video there is always session after which it ends. Creating, Updating, Clossing this Session is something that SIP is designed\nTo understand and have good debug skills it is important to know how SIP works in different situations. Here I will try to provide some simple documentation to help you BUILDERS.\nNext: Understanding SIP with Call Scenarios"},"title":"Guides"},"/diago/docs/guides/sip_and_media/":{"data":{"":"","undestanding-sip-and-media#Undestanding SIP and media":"INVITE carries SDP (application/sdp) in body of message as offer to explain media capabilites and connection setup. INVITE can have any other type in Body like HTTP, but SDP protocol is mainly used. More about this later.\nAccepting(Answering) call is done by respondin with 200 OK\nResponse carries SDP in body as answer to explain callee’s media capabilites and connection.\nCall with media With SDP we explain our capabilites and protocol used for media and this mostly boils down to this 3 things:\nexplaining which codecs are supported for decoding (alaw,ulaw, opus, g722, …), protocol and profile (RTP AVP). RTP can have different profile but AVP (Audio Video) is used in this case and Listen IP where we expect incoming media (UDP) Returning 200 For realtime media RTP is one mostly used. Anyway in case Bob has no similar capabilities, lets say codecs, Bob will send non 200 response and call will be terminated.\nSending ACK After Caller receiving 200 OK it is required that Caller acknowledge Callee capabilities, by sending ACK (non transactional, no response) request.\nCodecs Codecs or in other words Formats are identified as numbers. There are static defined by AVP profile or user can have any other defined with own custom numbers. In above case we use statically defined.\n0 ulaw 8000Hz 8 alaw 8000Hz In SDP this will be shown as m=desc key. Ex:\nm=audio 49170 RTP/AVP 0 8\nDescription:\naudio: type of stream 49170: port on which is listening RTP/AVP: identifier for RTP protocol and AVP denotes as Audio Video 0: is codec identifier Normally this should be followed with a=rtpmap attributes to explain about codecs. In case static this is not required.\nListen IP Information and where device/use is listening for incoming media traffic c=IN IP4 198.51.100.1\nIP4 denotes IP version 4 is used With nowdays NAT this unfortunatelly makes problem, as you can expect end user behind NAT will publish his private IP like 192.168.1.1. This is solved in different ways, but for now we will stop here. Other problem is if call is jumping between media servers, above can be changed with new IP received via new INVITE messaging.\nNOTE: Publishing local IP like above is problem for NAT and there different approaches to solve this issue, but for now we will skip this part."},"title":"SIP and Media"},"/diago/docs/guides/understanding_sip/":{"data":{"":"","#":"Every call starts with INVITE SIP Messages. Here is how to relate SIP message to PHONE actions\nDialing = INVITE Answer = 200 OK response on INVITE Hangup = BYE Cancel = CANCEL Reject = 486 Busy INVITE is creating session which we call dialog.\nCaller (Client): Sends one time ACK as confirmation\nSuccesfull call Example of alice inviting bob\nINVITE sip:bob@127.0.0.1:5060 SIP/2.0 Via: SIP/2.0/udp 127.0.0.99:50725;branch=z9hG4bK.pgb382qZ312tyXIP Content-Type: application/sdp Content-Length: 235 Contact: \u003csip:alice@127.0.0.99:50725\u003e;transport=udp From: \"alice\" \u003csip:alice@127.0.0.99\u003e;tag=hImscoj6Jew8y6da To: \u003csip:bob@127.0.0.1\u003e Call-ID: 729cd7dd-96dc-419b-b339-327c60dfc2d7 CSeq: 1 INVITE Max-Forwards: 70 Succesfull call with provisional responses (More realistic) Call establishment can take a while, so provisional responses help with this.\nProvisional responses = 1xx and mostly you will see 100 and 180. 100 is used in HTTP as well, it just notifies client that request is accepted but it is in progress.\nAfter very quickly you may have Ringing, which indicates that end user device is reached and it is ringing.\nCanceling call with SIP CANCEL Caller cancels call by sending CANCEL msg. It must contain same headers as INVITE for matching transcaction.\nCANCEL is new transaction request like INVITE which receives response, but SIP uses this request to try match existing INVITE transaction. That is why 200 OK is replied\nOnce Bob finds matching transcation it terminates and sends respond to INVITE with 487 Request terminated\nTO BE CONTINUED"},"title":"Understading SIP with Call Scenarios"}}
\ No newline at end of file