Pili Streaming Cloud server-side library for Rust

Features

• Stream Create,Get,List
  • hub.createStream()
  • hub.getStream()
  • hub.listStreams()
• Stream operations else
  • stream.toJsonString()
  • stream.update()
  • stream.disable()
  • stream.enable()
  • stream.status()
  • stream.rtmpPublishUrl()
  • stream.rtmpLiveUrls()
  • stream.hlsLiveUrls()
  • stream.httpFlvLiveUrls()
  • stream.segments()
  • stream.hlsPlaybackUrls()
  • stream.saveAs()
  • stream.snapshot()
  • stream.delete()

Contents

• Installation
• Dependencies
• Runtime Requirements
• Usage
  • Configuration
  • Hub
    • Instantiate a Pili Hub object
    • Create a new Stream
    • Get an exit Stream
    • List Streams
  • Stream
    • To JSON string
    • Update a Stream
    • Disable a Stream
    • Enable a Stream
    • Get Stream status
    • Generate RTMP publish URL
    • Generate RTMP live play URLs
    • Generate HLS live play URLs
    • Generate Http-Flv live play URLs
    • Get Stream segments
    • Generate HLS playback URLs
    • Save Stream as a file
    • Snapshot Stream
    • Delete a Stream
• History

Installation

You can download pili-sdk-java-v1.5.3.jar file in the release folder.

Dependencies

You also need okhttp, okio, Gson

Runtime Requirements

For Java, the minimum requirement is 1.7.

If you want to run the SDK on JDK 1.6 environment, you can download the compatible jar of okhttp and okio.

Usage

Configuration

  // Replace with your keys
  public static final String ACCESS_KEY = "Qiniu_AccessKey";
  public static final String SECRET_KEY = "Qiniu_SecretKey";

  // Replace with your hub name
  public static final String HUB = "Pili_Hub_Name"; // The Hub must be exists before use

  // Change API host as necessary
  //
  // pili.qiniuapi.com as default
  // pili-lte.qiniuapi.com is the latest RC version
  //
  // static {
  //    Configuration.getInstance().setAPIHost("pili.qiniuapi.com"); // default
  // }

Hub

Instantiate a Pili Hub object

  // Instantiate an Hub object
  Credentials credentials = new Credentials(ACCESS_KEY, SECRET_KEY); // Credentials Object
  Hub hub = new Hub(credentials, HUB_NAME); // Hub Object

Create a new stream

// Create a new Stream
  String title           = null;     // optional, auto-generated as default
  String publishKey      = null;     // optional, auto-generated as default
  String publishSecurity = null;     // optional, can be "dynamic" or "static", "dynamic" as default
  Stream stream = null;
  try {
      stream = hub.createStream(title, publishKey, publishSecurity);
      System.out.println("hub.createStream:");
      System.out.println(stream.toJsonString());
      /*
      {
          "id":"z1.test-hub.55d80075e3ba5723280000d2",
          "createdAt":"2015-08-22T04:54:13.539Z",
          "updatedAt":"2015-08-22T04:54:13.539Z",
          "title":"55d80075e3ba5723280000d2",
          "hub":"test-hub",
          "disabled":false,
          "publishKey":"ca11e07f094c3a6e",
          "publishSecurity":"dynamic",
          "hosts":{
              "publish":{
                  "rtmp":"ey636h.publish.z1.pili.qiniup.com"
               },
               "live":{
                   "hdl":"ey636h.live1-hdl.z1.pili.qiniucdn.com",
                   "hls":"ey636h.live1-hls.z1.pili.qiniucdn.com",
                   "rtmp":"ey636h.live1-rtmp.z1.pili.qiniucdn.com"
               },
               "playback":{
                   "hls":"ey636h.playback1.z1.pili.qiniucdn.com"
               }
           }
       }
       */
  } catch (PiliException e) {
      // TODO Auto-generated catch block
      e.printStackTrace();
  }

or

  try {
    Stream stream = hub.createStream();
  } catch (PiliException e) {
    e.printStackTrace();
  }

Get an exist Stream

  String streamId = stream.getStreamId();
  try {
    stream = hub.getStream(streamId);
    System.out.println("hub.getStream:");
    System.out.println(stream.toJsonString());
    /*
    {
        "id":"z1.test-hub.55d80075e3ba5723280000d2",
        "createdAt":"2015-08-22T04:54:13.539Z",
        "updatedAt":"2015-08-22T04:54:13.539Z",
        "title":"55d80075e3ba5723280000d2",
        "hub":"test-hub",
        "disabled":false,
        "publishKey":"ca11e07f094c3a6e",
        "publishSecurity":"dynamic",
        "hosts":{
            "publish":{
                  "rtmp":"ey636h.publish.z1.pili.qiniup.com"
             },
             "live":{
                  "hdl":"ey636h.live1-hdl.z1.pili.qiniucdn.com",
                  "hls":"ey636h.live1-hls.z1.pili.qiniucdn.com",
                  "rtmp":"ey636h.live1-rtmp.z1.pili.qiniucdn.com"
             },
             "playback":{
                  "hls":"ey636h.playback1.z1.pili.qiniucdn.com"
             }
         }
     }
     */
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

List Streams

  try {
      String status      = null;      // optional, can only be "connected"
      String marker      = null;      // optional
      long limit         = 0;         // optional
      String titlePrefix = null;      // optional

      StreamList streamList = hub.listStreams(status, marker, limit, titlePrefix);
      System.out.println("hub.listStreams()");
      System.out.println("marker:" + streamList.getMarker());
      System.out.println("isEnd:" + streamList.isEnd());
      List<Stream> list = streamList.getStreams();
      for (Stream s : list) {
          // access the stream
      }

      /*
       marker:10
       isEnd:false
       stream object
       */
  } catch (PiliException e) {
      // TODO Auto-generated catch block
      e.printStackTrace();
  }

or

  try {
    StreamList list = hub.listStreams();
    if (list != null) {
        for (Stream stream : list.getStreams()) {
            printStream(stream);
        }
    }
  } catch (PiliException e) {
    e.printStackTrace();
  }

Stream

To JSON string

String streamJsonString = stream.toJsonString();
System.out.println("Stream toJSONString()");
System.out.println(streamJsonString);

/*
    {
        "id":"z1.test-hub.55d80075e3ba5723280000d2",
        "createdAt":"2015-08-22T04:54:13.539Z",
        "updatedAt":"2015-08-22T04:54:13.539Z",
        "title":"55d80075e3ba5723280000d2",
        "hub":"test-hub",
        "disabled":false,
        "publishKey":"ca11e07f094c3a6e",
        "publishSecurity":"dynamic",
        "hosts":{
            "publish":{
                  "rtmp":"ey636h.publish.z1.pili.qiniup.com"
             },
             "live":{
                  "hdl":"ey636h.live1-hdl.z1.pili.qiniucdn.com",
                  "hls":"ey636h.live1-hls.z1.pili.qiniucdn.com",
                  "rtmp":"ey636h.live1-rtmp.z1.pili.qiniucdn.com"
             },
             "playback":{
                  "hls":"ey636h.playback1.z1.pili.qiniucdn.com"
             }
         }
     }
 */

Update a Stream

// Update a Stream
String newPublishKey       = "new_secret_words"; // optional
String newPublishSecurity  = "static";           // optional, can be "dynamic" or "static"
boolean newDisabled        = true;               // optional, can be "true" of "false"
try {
    Stream newStream = stream.update(newPublishKey, newPublishSecurity, newDisabled);
    System.out.println("Stream update()");
    System.out.println(newStream.toJsonString());
    stream = newStream;
    /*
    {
        "id":"z1.test-hub.55d80075e3ba5723280000d2",
        "createdAt":"2015-08-22T04:54:13.539Z",
        "updatedAt":"2015-08-22T01:53:02.738973745-04:00",
        "title":"55d80075e3ba5723280000d2",
        "hub":"test-hub",
        "disabled":true,
        "publishKey":"new_secret_words",
        "publishSecurity":"static",
        "hosts":{
            "publish":{
                  "rtmp":"ey636h.publish.z1.pili.qiniup.com"
             },
             "live":{
                  "hdl":"ey636h.live1-hdl.z1.pili.qiniucdn.com",
                  "hls":"ey636h.live1-hls.z1.pili.qiniucdn.com",
                  "rtmp":"ey636h.live1-rtmp.z1.pili.qiniucdn.com"
             },
             "playback":{
                  "hls":"ey636h.playback1.z1.pili.qiniucdn.com"
             }
         }
     }
 */
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Disable a Stream

// Disable a Stream
try {
    Stream disabledStream = stream.disable();
    System.out.println("Stream disable()");
    System.out.println(disabledStream.isDisabled());
    /*
     * true
     *
     * */
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Enable a Stream

// Enable a Stream
try {
    Stream enabledStream = stream.enable();
    System.out.println("Stream enable()");
    System.out.println(enabledStream.isDisabled());
    /*
     * false
     *
     * */
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Get Stream status

// Get Stream status
try {
    Status status = stream.status();
    System.out.println("Stream status()");
    System.out.println(status.toString());
    /*
    {
        "addr":"222.73.202.226:2572",
        "startFrom": "2015-09-10T05:58:10.289+08:00",
        "status":"connected",
        "bytesPerSecond":16870.200000000001,
        "framesPerSecond":{
            "audio":42.200000000000003,
            "video":14.733333333333333,
            "data":0.066666666666666666
         }
     }
    */
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Generate RTMP publish URL

// Generate RTMP publish URL
try {
    String publishUrl = stream.rtmpPublishUrl();
    System.out.println("Stream rtmpPublishUrl()");
    System.out.println(publishUrl);
    // rtmp://ey636h.publish.z1.pili.qiniup.com/test-hub/55d810aae3ba5723280000db?nonce=1440223404&token=hIVJje0ZOX9hp7yPIvGBmJ_6Qxo=

} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Generate RTMP live play URLs

// Generate RTMP live play URLs
String originUrl = stream.rtmpLiveUrls().get(Stream.ORIGIN);
System.out.println("Stream rtmpLiveUrls()");
System.out.println(originUrl);
// rtmp://ey636h.live1-rtmp.z1.pili.qiniucdn.com/test-hub/55d8113ee3ba5723280000dc

Generate HLS live play URLs

// Generate HLS play URLs
String originLiveHlsUrl = stream.hlsLiveUrls().get(Stream.ORIGIN);
System.out.println("Stream hlsLiveUrls()");
System.out.println(originLiveHlsUrl);
// http://ey636h.live1-http.z1.pili.qiniucdn.com/test-hub/55d8119ee3ba5723280000dd.m3u8

Generate Http Flv live play URLs

// Generate Http-Flv live play URLs
String originLiveFlvUrl = stream.httpFlvLiveUrls().get(Stream.ORIGIN);
System.out.println("Stream httpFlvLiveUrls()");
System.out.println(originLiveFlvUrl);
// http://ey636h.live1-http.z1.pili.qiniucdn.com/test-hub/55d8119ee3ba5723280000dd.flv

Get Stream segments

// Get Stream segments
long start = 0;    // optional, in second, unix timestamp
long end   = 0;    // optional, in second, unix timestamp
int limit  = 0;    // optional, int
try {
    SegmentList segmentList = stream.segments(start, end, limit);
    System.out.println("The earliest data of stream:" + segmentList.getStart()
            + ",the latest data of stream:" + segmentList.getEnd());

    System.out.println("The duration of the current segment:" + segmentList.getDuration());

    System.out.println("Stream segments()");
    for (Segment segment : segmentList.getSegmentList()) {
        System.out.println("start:" + segment.getStart() + ",end:" + segment.getEnd());
    }
    /*
         The earliest data of stream:1444298545,the latest data of stream:1444298612
         The duration of the current segemnt:67
         start:1440315411,end:1440315435
     */
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Generate HLS playback URLs

// Generate HLS playback URLs
long startHlsPlayback     = 1440315411;  // required, in second, unix timestamp
long endHlsPlayback       = 1440315435;  // required, in second, unix timestamp
try {
    String hlsPlaybackUrl = stream.hlsPlaybackUrls(startHlsPlayback, endHlsPlayback).get(Stream.ORIGIN);

    System.out.println("Stream hlsPlaybackUrls()");
    System.out.println(hlsPlaybackUrl);
    // http://ey636h.playback1.z1.pili.qiniucdn.com/test-hub/55d8119ee3ba5723280000dd.m3u8?start=1440315411&end=1440315435
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

If you set illegal values to startHlsPlayback and endHlsPlayback, the query parameters of start and end will be set to -1.

For example,

// both startHlsPlayback <= 0 , endHlsPlayback <= 0, and startHlsPlayback > endHlsPlayback are illegal values.
long startHlsPlayback     = -1;  // <= 0
long endHlsPlayback       = -1;  // <= 0
try {
    String hlsPlaybackUrl = stream.hlsPlaybackUrls(startHlsPlayback, endHlsPlayback).get(Stream.ORIGIN);

    System.out.println("Stream hlsPlaybackUrls()");
    System.out.println(hlsPlaybackUrl);
    // http://ey636h.playback1.z1.pili.qiniucdn.com/test-hub/55d8119ee3ba5723280000dd.m3u8?start=-1&end=-1
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Save Stream as a file

// Save Stream as a file
String saveAsFormat    = "mp4";                            // required
String saveAsName      = "videoName" + "." + saveAsFormat; // required
long saveAsStart       = 1440315411;                       // required, in second, unix timestamp
long saveAsEnd         = 1440315435;                       // required, in second, unix timestamp
String saveAsNotifyUrl = null;                             // optional
try {
    SaveAsResponse response = stream.saveAs(saveAsName, saveAsFormat, saveAsStart, saveAsEnd, saveAsNotifyUrl);
    System.out.println("Stream saveAs()");
    System.out.println(response.toString());
    /*
     {
         "url":"http://ey636h.vod1.z1.pili.qiniucdn.com/recordings/z1.test-hub.55d81a72e3ba5723280000ec/videoName.m3u8",
         "targetUrl":"http://ey636h.vod1.z1.pili.qiniucdn.com/recordings/z1.test-hub.55d81a72e3ba5723280000ec/videoName.mp4",
         "persistentId":"z1.55d81c6c7823de5a49ad77b3"
     }
    */
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

While invoking saveAs() and snapshot(), you can get processing state via Qiniu fop service using persistentId.
API: curl -D GET http://api.qiniu.com/status/get/prefop?id={persistentId}
Doc reference: http://developer.qiniu.com/docs/v6/api/overview/fop/persistent-fop.html#pfop-status

Snapshot Stream

// Snapshot Stream
String format    = "jpg";                      // required
String name      = "imageName" + "." + format; // required
long time        = 1440315411;                 // optional, in second, unix timestamp
String notifyUrl = null;                       // optional

try {
    SnapshotResponse response = stream.snapshot(name, format, time, notifyUrl);
    System.out.println("Stream snapshot()");
    System.out.println(response.toString());
    /*
     {
         "targetUrl":"http://ey636h.static1.z1.pili.qiniucdn.com/snapshots/z1.test-hub.55d81a72e3ba5723280000ec/imageName.jpg",
         "persistentId":"z1.55d81c247823de5a49ad729c"
     }
     */
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Delete a stream

// Delete a Stream
try {
    String res = stream.delete();
    System.out.println("Stream delete()");
    System.out.println(res);
    // No Content
} catch (PiliException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

History

• 1.5.3

  • listStreams return 0 item if no stream instead of Exception
  • update hlsPlaybackUrls API by saveAs
  • remove the check of format argument for saveAs
  • add SaveAsResponse saveAs(String fileName, long startTime, long endTime)

• 1.5.2

  • Add start, end, and duration attributes into SegmentList
  • Add end into StreamList
  • Update hlsPlaybackUrls API

• 1.5.1

  • Update Stream's hosts
  • Add startFrom into Stream status
  • Add status query parameter for listStreams

• 1.5.0

  • Add Stream Create,Get,List
    • hub.createStream()
    • hub.getStream()
    • hub.listStreams()
  • Add Stream operations else
    • stream.toJsonString()
    • stream.update()
    • stream.disable()
    • stream.enable()
    • stream.status()
    • stream.segments()
    • stream.rtmpPublishUrl()
    • stream.rtmpLiveUrls()
    • stream.hlsLiveUrls()
    • stream.httpFlvLiveUrls()
    • stream.hlsPlaybackUrls()
    • stream.snapshot()
    • stream.saveAs()
    • stream.delete()