# oss-streaming

Part of **OSS**

# Object Storage Service Streaming Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|--------|--------|---------|------------------|
| Malformed RTMP Ingest URL | Error 400: Bad Request | High | Escape special characters (e.g., `&`) in the RTMP URL or wrap it in quotes |
| Authentication Failure | Error 403: Forbidden | High | Verify OSSAccessKeyId and Signature in the signed RTMP URL |
| Incomplete Stream Data | Error 500: Internal Server Error | Medium | Ensure complete AAC/AVC sequence headers are sent at stream start |
| Missing M3U8 Playlist | Playlist file not generated or updated | Medium | Confirm `playlistName` parameter is correctly included in the ingest URL |
| Playback Stuttering or Buffering | Video/audio stutters during playback | Low | Adjust `FragDuration` and `FragCount` to optimize segment size and count |

## Problem Details

### Problem 1: Malformed RTMP Ingest URL Causes 400 Error

**Symptoms**
- Error message: `400 Bad Request`
- Behavior: Stream ingest fails immediately upon connection
- Context: Occurs when using command-line tools like `ffmpeg` with an RTMP URL containing unescaped special characters (e.g., `&`)

**Root Cause**
The RTMP ingest URL includes query parameters (e.g., `Expires`, `OSSAccessKeyId`, `Signature`, `playlistName`). If the URL is not properly quoted or escaped in shell commands, the shell interprets `&` as a background job operator, truncating the URL and causing a malformed request.

**Solution**
1. When using `ffmpeg` or similar tools in bash, always wrap the full RTMP URL in double quotes.
2. Alternatively, escape special characters like `&` with a backslash (`\&`), though quoting is preferred.

Example of correct usage:
```bash
ffmpeg -re -i input.aac -acodec aac -strict -2 -f flv "rtmp://xxx.oss-cn-beijing.aliyuncs.com/live/test_1000?Expires=1540458859&OSSAccessKeyId=LTAlujianb****&Signature=qwh31xQsanmao6ygCFJgo****%3D&playlistName=playlist.m3u8"
```

**Verification**
- Run the command and observe successful stream ingestion in OSS console.
- Confirm that `.m3u8` and `.ts` files appear in the target bucket under the LiveChannel directory.

### Problem 2: Authentication Failure During Stream Ingest

**Symptoms**
- Error message: `403 Forbidden`
- Behavior: Connection is rejected before stream data is accepted
- Context: Occurs when the signed RTMP URL contains invalid or expired credentials

**Root Cause**
The `OSSAccessKeyId` or `Signature` in the RTMP URL is incorrect, expired, or improperly URL-encoded. The `Expires` timestamp may be in the past, or the signature may not match the expected HMAC-SHA1 hash of the canonical request.

**Solution**
1. Regenerate a valid signed RTMP ingest URL with a future expiration time.
2. Ensure the `Signature` is correctly computed using your AccessKeySecret and properly URL-encoded (e.g., `%3D` for `=`).
3. Validate the URL structure matches the OSS LiveChannel ingest format.

**Verification**
- Use the corrected URL with `ffmpeg` or OBS.
- Monitor the OSS console for new segments appearing within 10–30 seconds of ingest start.

### Problem 3: Incomplete Codec Headers Cause 500 Error

**Symptoms**
- Error message: `500 Internal Server Error`
- Behavior: Stream connects but fails shortly after data transmission begins; no TS segments are created
- Context: Common when streaming raw audio (e.g., AAC) or video (e.g., H.264) without proper sequence headers

**Root Cause**
OSS LiveChannel requires complete codec configuration headers (e.g., AAC sequence header or AVCDecoderConfigurationRecord) at the beginning of the stream. If the encoder (e.g., `ffmpeg`) does not send these headers—often due to incorrect codec settings or input format—the service cannot parse the stream and returns a 500 error.

**Solution**
1. For AAC audio, ensure the input file contains ADTS headers or use `-bsf:a aac_adtstoasc` if needed.
2. For H.264 video, confirm the stream includes SPS/PPS NAL units at the start.
3. Use standard encoding profiles that emit full headers:

```bash
ffmpeg -re -i input.mp4 -c:v libx264 -preset ultrafast -tune zerolatency -c:a aac -f flv "rtmp://..."
```

**Verification**
- After re-ingesting, check that `.ts` files are generated and contain valid media data.
- Play the `.m3u8` URL in a compatible HLS player (e.g., VLC) to confirm audio/video playback.

### Problem 4: M3U8 Playlist Not Generated

**Symptoms**
- No `playlist.m3u8` file appears in the LiveChannel directory
- Behavior: TS segments may exist, but no playlist to reference them
- Context: Occurs when the `playlistName` parameter is missing or malformed in the ingest URL

**Root Cause**
The `playlistName` query parameter is required to specify the name of the output HLS playlist (e.g., `playlist.m3u8`). If omitted, OSS does not generate a manifest file, making playback impossible.

**Solution**
1. Include `&playlistName=your_playlist.m3u8` in the signed RTMP URL.
2. Ensure the playlist name ends with `.m3u8` and uses valid characters.

Example:
```bash
ffmpeg -re -i input.aac -acodec aac -strict -2 -f flv "rtmp://.../test_1000?Expires=...&Signature=...&playlistName=live.m3u8"
```

**Verification**
- After starting the stream, verify that both `live.m3u8` and associated `.ts` files appear in the bucket.
- Fetch the `.m3u8` URL via HTTP and confirm it lists recent segments.

### Problem 5: Playback Stuttering or Excessive Buffering

**Symptoms**
- Video/audio playback stutters, pauses, or buffers frequently
- Behavior: Player loads segments slowly or skips frames
- Context: Occurs during live or on-demand playback of HLS streams from OSS

**Root Cause**
Suboptimal `FragDuration` (segment duration) and `FragCount` (number of segments in playlist) settings can cause players to buffer excessively or miss segments. Very short fragments increase HTTP requests; very long ones delay startup and reduce responsiveness.

**Solution**
1. Set `FragDuration` between 2–10 seconds (default is often 5s).
2. Set `FragCount` to at least 3–5 to maintain a stable sliding window.
3. Configure these via LiveChannel creation API or update operation (not in the RTMP URL).

Example (via API):
```json
{
  "Target": "HLS",
  "FragDuration": 5,
  "FragCount": 5,
  "PlaylistName": "live.m3u8"
}
```

**Verification**
- Observe smoother playback in HLS-compatible players.
- Check that the `.m3u8` file consistently lists the expected number of segments with stable durations.

## FAQ

**Q: How do I generate a valid signed RTMP URL for stream ingest?**  
A: Construct a URL with `Expires`, `OSSAccessKeyId`, and `Signature` parameters. The `Signature` must be an HMAC-SHA1 hash of the canonical string (including resource path and query parameters except `Signature`), base64-encoded and URL-encoded. Use OSS SDKs or signing utilities to avoid manual errors.

**Q: Why are my TS segments not appearing even though ffmpeg shows “connected”?**  
A: This usually indicates a codec header issue (Error 500) or missing `playlistName`. Verify that your stream includes proper AAC/AVC sequence headers and that the ingest URL specifies a valid `playlistName`.

**Q: What permissions are required to create or ingest into a LiveChannel?**  
A: The OSS user must have `oss:PostVodPlaylist` and `oss:PutLiveChannel` permissions on the target bucket. Additionally, the signed RTMP URL must be generated with valid credentials that have write access to the bucket.

**Q: Can I use OBS Studio to stream to OSS LiveChannel?**  
A: Yes. In OBS, set the service to “Custom” and paste the full signed RTMP URL (including all query parameters) into the “Server” field. Leave the “Stream Key” blank or include it in the URL path if needed. Always test with a short stream first.

**Q: How do I debug stream ingest issues?**  
A: Enable verbose logging in your encoder (e.g., `ffmpeg -loglevel debug`), validate the RTMP URL structure, check OSS bucket logs for 4xx/5xx responses, and confirm network connectivity to the OSS endpoint. Also, verify that the total stream bitrate does not exceed 10 Mbps per LiveChannel.