opusrtp: Update help and manual page
authorMark Harris <mark.hsj@gmail.com>
Tue, 18 Sep 2018 04:51:10 +0000 (21:51 -0700)
committerMark Harris <mark.hsj@gmail.com>
Tue, 18 Sep 2018 08:13:07 +0000 (01:13 -0700)
man/opusrtp.1
src/opusrtp.c

index e4297b0..51b4a1d 100644 (file)
@@ -4,41 +4,76 @@
 .TH opusrtp 1 2012-08-31 "Xiph.Org Foundation" "opus-tools"
 
 .SH NAME
-opusrtp \- encapsulate Opus audio in RTP
+opusrtp \- transmit or receive an Opus audio RTP stream
 
 .SH SYNOPSIS
+.sp
 .B opusrtp
 [
-.B -hV
+.B transmit-options
 ]
-[
+.B in.opus ...
+.sp
+.B opusrtp
 .B --sniff
+.I device
+[
+.B receive-options
 ]
-.B file.opus
+.sp
+.B opusrtp
+.B --extract
+.I in.pcap
 [
-.B file2.opus ...
+.B receive-options
 ]
+.sp
+.B opusrtp
+.B --help
+.sp
+.B opusrtp
+.B --version
 
 .SH DESCRIPTION
 
 .B opusrtp
-Demonstration tool for sending and receiving Opus audio data in RTP,
+is an experimental tool to transmit and receive Opus audio RTP streams,
 used for interactive applications on the internet.
 
-By default, Opus audio from each given file is sent as an RTP stream.
-
 .SH "OPTIONS"
+.SS "General options"
 .IP "-h, --help"
-Print help message
+Show command help
 .IP "-V, --version"
-Display version information
-.IP "--quiet"
-Suppresses program output
-.IP "--sniff"
-Sniff the network for active RTP sessions and save them to .opus
-files. This can be useful for debugging other Opus RTP implementations.
-For this function to work, the program must be run with superuser
-privileges.
+Show version information
+
+.SS "Transmit options"
+.IP "-d, --destination addr"
+Set destination IP address (default 127.0.0.1)
+.IP "-p, --port n"
+Set destination port (default 1234)
+.IP "-t, --type n"
+Set RTP payload type (default 120)
+
+.SS "Receive options"
+.IP "--sniff device"
+Sniff the network device for active RTP sessions, which can be
+useful for debugging other Opus RTP implementations.  This may
+require superuser privileges.
+.IP "-e, --extract in.pcap"
+Extract from input pcap file
+.IP "-p, --port n"
+Set destination port to capture. By default, the first plausible
+port number that is seen is captured.
+.IP "-t, --type n"
+Set RTP payload type to capture. By default, the first plausible
+dynamic payload type that is seen is captured.
+.IP "-o, --output out.opus"
+Write Ogg Opus output file
+.IP "-r, --rate n"
+Set original sample rate in Ogg Opus output file (default 48000)
+.IP "-c, --channels n"
+Set channel count in Ogg Opus output file (default 2)
 
 .SH AUTHORS
 .br
@@ -46,11 +81,9 @@ Ralph Giles <giles@thaumas.net>
 
 .SH BUGS
 
-Only the sniff mode is implemented; the tool should do normal unicast
-and multicast send/receive.
-
-The sniff mode should allow specifying device/host/port/payload type
-to limit capture. All that is hard-coded.
+The receive mode does not support out-of-order or missing packets,
+multiple simultaneous RTP streams with the same destination port
+number and payload type, or normal unicast and multicast receive.
 
 .SH SEE ALSO
 .BR opusdec (1),
index 063bb5e..d405112 100644 (file)
@@ -1190,25 +1190,28 @@ void opustools_version(void)
   printf("Copyright (C) 2012-2018 Xiph.Org Foundation\n");
 }
 
-void usage(char *exe)
+void usage(void)
 {
-  printf("Usage: %s [--extract file.pcap] [--sniff <device>] <file.opus> [<file2.opus>]\n", exe);
+  printf("Transmit Opus RTP stream:\n");
+  printf("  opusrtp [transmit-options] in.opus ...\n");
+  printf("    -d, --destination addr Set destination IP address (default 127.0.0.1)\n");
+  printf("    -p, --port n           Set destination port (default 1234)\n");
+  printf("    -t, --type n           Set RTP payload type (default 120)\n");
   printf("\n");
-  printf("Sends and receives Opus audio RTP streams.\n");
-  printf("\nGeneral Options:\n");
-  printf(" -h, --help             Show this help\n");
-  printf(" -V, --version          Show version information\n");
-  printf(" -q, --quiet            Suppress status output\n");
-  printf(" -d, --destination addr Set destination IP address (default 127.0.0.1)\n");
-  printf(" -p, --port n           Set destination port (default 1234)\n");
-  printf(" -o, --output out.opus  Write Ogg Opus output file\n");
-  printf(" -r, --rate n           Set output file sample rate (default 48000)\n");
-  printf(" -c, --channels n       Set output file channel count (default 2)\n");
-  printf(" -t, --type n           Set RTP payload type (default 120)\n");
-  printf(" --sniff device         Sniff device for Opus RTP streams\n");
-  printf(" -e, --extract in.pcap  Extract from input pcap file\n");
+  printf("Receive Opus RTP stream:\n");
+  printf("  opusrtp [receive-options]  (specify one of --sniff or --extract)\n");
+  printf("    --sniff device         Sniff device for Opus RTP streams\n");
+  printf("    -e, --extract in.pcap  Extract from input pcap file\n");
+  printf("    -p, --port n           Set destination port to capture\n");
+  printf("    -t, --type n           Set RTP payload type to capture\n");
+  printf("    -o, --output out.opus  Write Ogg Opus output file\n");
+  printf("    -r, --rate n           Set original sample rate (default 48000)\n");
+  printf("    -c, --channels n       Set channel count (default 2)\n");
+  printf("\n");
+  printf("Display help or version information:\n");
+  printf("  opusrtp -h|--help\n");
+  printf("  opusrtp -V|--version\n");
   printf("\n");
-  printf("By default, the given file(s) will be sent over RTP.\n");
 }
 
 int main(int argc, char *argv[])
@@ -1287,11 +1290,11 @@ int main(int argc, char *argv[])
             payload_type = atoi(optarg);
         break;
       case 'h':
-        usage(argv[0]);
+        usage();
         return 0;
       case '?':
       default:
-        usage(argv[0]);
+        usage();
         return 1;
     }
   }
@@ -1331,6 +1334,6 @@ int main(int argc, char *argv[])
 #endif
   }
 
-  usage(argv[0]);
+  usage();
   return 1;
 }