LinkVisual FAQ

API request returns "Request is forbidden"

The LinkVisual service is not activated. For more information, see Quick start with LinkVisual.

API request returns "Stream push failed"

The product is missing the required Thing Specification Language model for the feature. Check the Thing Specification Language model descriptions for each feature to identify and add any missing models. For more information, see Add a standard feature.

For example, if you do not select the StartVoiceIntercom service in the Thing Specification Language model for the voice intercom feature, you will receive this error when you initiate an intercom request.

Why is the time to first frame long?

If a device responds to a force I-frame instruction within 300 ms, the time to first frame (TTFF) is typically less than 1.5 seconds. This is a common scenario on an office Wi-Fi network.

TTFF = Time to request playback URL (300 ms) + Time to connect to playback URL (150 ms) + Time to wait for device I-frame (300 ms) + Player internal buffer delay (200 ms) + Time to decode and render (10 ms)

A long TTFF is usually caused by one of the following two reasons.

• The device does not correctly respond to the force I-frame instruction. This adds a delay equal to the length of one Group of Pictures (GOP). To resolve this, ensure that the device correctly responds to the force I-frame instruction.

• The device takes a long time to connect to the ingest URL. In this case, you can contact us by submitting a ticket in the upper-right corner of the console.

Why does live playback stutter?

Playback stuttering and frame skipping are usually caused by the following reasons.

• The device SDK buffer is too small

  The LinkVisual device software development kit (SDK) provides an interface to set the stream bitrate. The SDK calculates and sets the buffer size based on the specified bitrate. If the bitrate is set too low, the device SDK buffer frequently triggers packet loss, which degrades video quality. To resolve this, set an appropriate buffer size for the SDK.

  Note

  LinkVisual does not support stream transmission for frames larger than 512 KB.

• Poor device network

  If the upstream bandwidth of the device's network is insufficient for the set stream bitrate, the device SDK buffer frequently drops packets, which degrades video quality. To resolve this, adjust the device's location or check its network status.

• Poor playback-side network

  The downstream bandwidth on the playback side must be greater than the current stream bitrate. The player provides an interface to retrieve the current stream information. You can check whether the playback-side network bandwidth meets the requirement. We recommend that you display the current stream information, such as "24 fps 80 KB/s", to help with future troubleshooting.

• Stream issues

  LinkVisual does not support B-frames. For H.264, we recommend that you use the Baseline or Main profile.

  The following table lists the maximum bitrates for different resolutions.

  Encoding format	Resolution	Maximum bitrate
  H.264	1080P	<2 Mbps
  	720P	<1 Mbps
  	D1	<0.5 Mbps
  H.265	1080P	<1.5 Mbps
  	720P	<0.75 Mbps
  	D1	<0.5 Mbps

• Long decoding time

  If the encoding is complex or frames are too large, the decoding time increases. This can cause the player to actively drop frames, which results in stuttering. To resolve this, reduce the encoding complexity and stream size on the device.

• Abnormal device timestamp

  The difference in the Presentation Timestamp (PTS) or Decoding Timestamp (DTS) between two consecutive frames should match the actual timestamp difference when the encoder generated the frames.

  • If the timestamp difference is larger than the actual difference, the player's decoder delays decoding. This can cause the player buffer to overflow and drop frames, resulting in slow-motion video and stuttering.

  • If the timestamp difference is smaller than the actual difference, the player's decoder decodes frames early. This results in fast-motion video.

  Note

  We recommend that you use the stream self-check feature of the device SDK to check timestamps.

Live playback disconnects

If the video freezes for a period and then an error is reported, the cause is usually one of the following.

• Abnormal stream ingest from the device

  The stream ingest is suddenly interrupted because of a network disconnection or a program bug. If the cause is not the network, you can analyze the device logs to rule out bugs.

• Poor playback-side network

  If the player cannot pull the stream for a period or detects a network disconnection, it reports an error to the upper layer. This is expected behavior.

  Note

  For a stream pulling error (1100) on the playback side, we recommend that you implement a retry logic in the app for one to two attempts. If the error persists, present a retry option to the user.

Screen tearing occurs during resolution switching

IP cameras (IPCs) switch between multiple streams to change the resolution. When the device responds to a resolution switching instruction, it switches the ingest stream from stream 1 to stream 2. The device must immediately stop ingesting stream 1 and wait for the I-frame of the next GOP in stream 2 to start the new ingest. You must check your business logic to ensure that it follows this process.

Record-while-playing fails

The player starts recording only after it receives an I-frame. If the time between starting and stopping the recording is too short and no I-frame is received, the recording fails. You must also ensure that there is enough free space on the mobile phone to save the recorded MP4 file.

We recommend that you implement the following limits or reminders.

• Set a minimum recording duration in the app. If a user's recording action is too short, display a prompt. Do not allow the stop recording interface to be called if the duration is significantly shorter than one GOP.

• Set a maximum recording duration in the app. Before each recording starts, check whether there is enough free space to store a file of the maximum duration.

Querying the SD card recording list returns "Service timed out"

The app requests the list of on-demand device recordings through the Thing Specification Language model service. The request returns the following error.

code:20056
message:gateway.hsf.invoke.timeout
localizedMsg:Backend service timed out

The main reason for this issue is that the device failed to process the SD card recording query within the specified synchronous service timeout period of 3 seconds.

We recommend that you optimize the query speed, for example, by creating file indexes. Ensure that data queries for a 24-hour period can be completed within 3 seconds.

Slow seek response for SD card recordings

Optimization suggestion: For large files, add indexes within the file to quickly locate the I-frame near a specified time. You must also ensure that the first frame pushed is an I-frame.

Abnormal playback speed for SD card recordings

Unlike live streaming where video frames are generated and sent in real time, the ingest rate and timestamps for on-demand SD card recordings are manually controlled. Improper control can affect playback.

The following are common phenomena.

Playing SD card recording by file, file duration is always 0

This usually occurs because the device SDK did not retrieve the file length before starting the stream ingest. You can check the device logs to confirm whether the correct duration was returned to the SDK.

Playback is normal during record-while-playing, but the saved MP4 file has frame skips or screen tearing

This is usually related to abnormal device timestamps. If the playback side receives two consecutive video frames with the same timestamp, frames are dropped during MP4 recording, which causes screen tearing or frame skipping. This issue must be fixed on the device.

Some users experience playback failure when multiple users watch the same SD card recording simultaneously

By default, the device SDK supports only one concurrent viewer. When there are multiple viewers, the last user to connect preempts the session and can watch normally.

Optimization suggestion: The device SDK lets you adjust the number of concurrent streams. The default is one. You can adjust the concurrency parameter based on your device's capabilities and business scenario. We recommend that you do not exceed four concurrent streams.

How to add custom information to the stream extension

Device manufacturers can use Supplemental Enhancement Information (SEI) frames to add custom information to the video stream, such as algorithm annotation data or fisheye correction information.

The SEI frames must comply with the standard definitions in H.264/H.265. The LinkVisual player can receive custom SEI binary data. This data is the entire SEI Network Abstraction Layer (NAL) unit, excluding the NAL start code (0x00 0x00 0x01 or 0x00 0x00 0x00 0x01).

Video resolution changes during playback of the same cloud recording

This is expected behavior. Cloud recording uploads and live streaming share the same channel. If the resolution of the live stream changes during the cloud recording period, the resolution of the corresponding cloud recording also changes.

Continuous cloud recordings are not contiguous

This issue is usually caused by the following reasons.

• The device restarted. Check the device logs.

• The device went offline because of network issues. You can check the device logs. You can find the offline time in the IoT Platform console.

• The device's stream ingest was abnormally interrupted. Check the device logs.

• The resolution was changed during a single H.265 stream ingest session. If the resolution is changed during H.265 stream ingest, the cloud recording service generates a new segment. Queries will treat this as two separate files.

beginTime from cloud recording query API does not match OSD watermark time in the video file

The `beginTime` is generated based on the server time when the streaming media server receives the first video I-frame. The OSD watermark time is based on the device time. The server clock error is controllable and close to UTC. However, embedded devices can have significant time errors because of their built-in clocks and time synchronization policies. In addition to clock inaccuracies, check whether the device's video frame buffer is too large, which sacrifices real-time performance and causes the server to receive data later than expected. The error can be calculated with this formula: Error = Device clock error + Device video frame buffer delay + Network latency (< 500 ms) + Server-side processing time (< 100 ms). In theory, the total error should be controlled within 2 seconds.

Can the cloud recording player record while playing?

Yes. It also supports downloading cloud recordings, which you can play after they are downloaded.

What is the storage period for event images?

After you activate the LinkVisual service, each device receives 3 days of free cloud storage for images. This may be adjusted in the future. For specific package details, refer to your official contract.

Cannot find the corresponding event recording based on a push notification

This issue is usually caused by one of the following two reasons. You can take action based on your specific situation.

• The minimum interval for reporting events is 10 seconds, regardless of the event type. If the device reports events at a shorter interval, event throttling is triggered, and no recording is generated. You can add a filter on the device to enforce the minimum interval and confirm that the interval is greater than 10 seconds.

• Because of network issues, the device might successfully report an event but fail to respond to the stream ingest request. You can check the network environment or retry later.

How to handle different time zones between the app and the device?

The app and the device may be in different time zones. To ensure time accuracy, the LinkVisual SDK and server-side APIs use UTC.

The following example uses the on-demand device recording feature to show how to implement the business process of "querying and playing device recordings based on device time".

• Set the device time zone

  1. After the app is paired with the device, it sends the default time zone configuration to the device through the time zone property in the Thing Specification Language model.

  2. Users can change the device time zone on the app's settings page.

  3. The device's OSD (on-screen display) watermark shows the time in the device's local time zone. The PTS/DTS timestamps use UTC and are saved with the frames in the recording file.

• The app playback request flow is as follows

  1. The app's calendar and timeline display the current date and time according to the device's time zone.

  2. When the user selects a time range to watch (for example, 00:00 to 24:00 in the device's time), the app retrieves the UTC timestamps for this range and sends them to the device as `beginTime` and `endTime` to query the recording list.

  3. The device filters the recording file segments based on `beginTime` and `endTime` and returns them to the app (device responds to the query).

  4. The app converts the UTC time returned by the device to the device's local time zone for display. This ensures the displayed time is always consistent with the OSD time (app display and playback).

Cannot hear intercom audio on the device

• Check whether the app has permission to record audio.

• Check whether the speaker property is enabled in the device's Thing Specification Language model.

Loud screeching noise during two-way audio when the phone and device are close

Screeching during close-range two-way audio is difficult to resolve. Avoid using two-way audio when the devices are close. If you encounter this situation, you can reduce the noise by lowering the speaker volume on one device or covering its microphone.

Why is there an echo during two-way audio?

First, determine which device is causing the echo, and then take the appropriate action.

• If you speak into the device and hear an echo of your own voice on the device

  This is because the phone's echo cancellation is not effective. The two-way audio solution uses hardware-based Acoustic Echo Cancellation (AEC). The echo cancellation effect is good on iOS phones. It is also effective on most Android phones. If you find an Android phone with poor echo cancellation, please provide feedback to us.

• If you speak into the phone and hear an echo of your own voice on the phone

  This is because the device's echo cancellation is not effective. Possible reasons include the following:

  • The echo cancellation algorithm is not enabled on the device.

  • Poor isolation between the microphone and speaker due to the cavity structure design.

  • The speaker is distorted.

  • The microphone gain is set too high, causing audio clipping.

  If the device's echo cancellation issue cannot be resolved and does not meet the requirements for two-way audio, we recommend that you switch to a one-way audio solution.

Receive error "code":9543 "message":"voice intercom existed" during voice intercom

You will receive this error in the following two situations.

• Starting and stopping the intercom too quickly in the app

  For example, if you quickly toggle the intercom on and off, the device may still be processing the previous request to end the intercom and cannot respond to the new request. This is expected behavior.

  After you end an intercom session, do not immediately start a new one. You can add safeguards and prompts in the app to handle frequent user operations.

• Device error

  For example, the device is unable to respond to the next intercom request. This is a bug and requires further analysis of the device logs.

Android player has audio but no video when using GLSurfaceView, but screenshots can be captured

Follow these steps to troubleshoot the issue.

1. Check whether a background color is set for the GLSurfaceView or its container. If so, remove it.

2. In the Activity's `onResume()` and `onPause()` callback methods, check whether the `onResume()` and `onPause()` methods of the GLSurfaceView are missing.

Why does the Android VodPlayer receive an onError callback with a "pull stream error" message after playback ends?

The on-demand device recording feature does not automatically close the connection after playback is complete. You must call `stop()` after you receive the OnCompletionListener.onComplete() callback to close the connection. Otherwise, this error is reported after 8 seconds.

After turning down the volume on an Android phone, the volume suddenly increases when the intercom is turned on

On Android, volume is configured separately for different stream types. By default, the volume keys control the Music stream volume. When the intercom is on, it uses the Phone Call stream volume. Check whether the Phone Call volume on your phone is set to maximum. You can use `AudioManager` to adjust the Phone Call stream volume.