SPlayer lifecycle

The splayer_api struct, defined in splayerapi-5.h, serves as the main interface for controlling the SDK. It provides all necessary functions to initialize, operate, and cleanly shut down the player.

1. Initialization

The lifecycle begins by creating an player context via the splayer_api->create() function. This call allocates and initializes internal resources and returns a pointer to a splayer_t instance. This handle must be passed to other API functions for operations such as authentication, playback control, and metadata handling.

Once the context is successfully created, the player is considered active. Multiple internal threads are spawned by the SDK during this process. These threads remain active until the player is shut down.

2. Monitoring and Shutdown Handling

After the player context is created, the SDK manages its own internal threads and continues running independently in the background.

To determine when the player intends to shut down, your application should regularly check the return value of splayer_api->should_exit(). This function returns 1 when the player is ready to exit. A good guideline is to check this value every 500ms in your application to determine when to begin the shutdown sequence.

Calling splayer_api->request_exit() signals the player to begin shutting down which initializes the shutdown process of the SPlayer in a controlled and responsive manner.

3. Clean Shutdown

To shut down the player cleanly, follow this two-step process:

1. Request Shutdown
   Call splayer_api->request_exit(), passing the player context and an appropriate exit reason from the splayer_exit_t enum.

2. Free Resources
   After request_exit() is called and should_exit() returns 1, you must call splayer_api->free() to release all allocated resources. Failing to call this function will result in a memory leak.