Docs

Embed Player

Introduction

This embedded player consists of a TikTok post hosted inside of an inline frame (iframe) element. This player allows you to do the following:

Customize the player by appending query parameters in the iframe URL. For example, you can display the music information of this video using the "description" parameter, or you can hide the video controls using the "controls" parameter.
Control the player by messaging the HTML host to enable functionality like playing, pausing, muting, and more.

See more on the custom options and messaging communication below.

Get started

First locate the TikTok post you want to embed in the player. The post URL follows this structure: www.tiktok.com/player/v1/{tiktok_post_id}.

View the following example: https://www.tiktok.com/player/v1/6718335390845095173

You can find the TikTok post ID on from the post URL. For example, 6718335390845095173 is the post ID from the URL https://www.tiktok.com/@scout2015/video/6718335390845095173

Customize the player

You can customize the player by choosing which playback interface elements should be hidden or displayed.

For example, this URL displays the TikTok post's music info and the description: https://www.tiktok.com/player/v1/6718335390845095173?music_info=1&description=1

Name	Description	Post type
controls	1: Display the progress bar and all the control buttons, such as the playvolume control and fullscreen buttons 0: Hide the progress bar and all control buttons Default to 1	video, image
progress_bar	1: Display the progress bar 0: Hide the progress bar Default to 1	video
play_button	1: Display the play button 0: Hide the play button Default to 1	video
volume_control	1: Display the volume control button 0: Hide the volume control button Default to 1	video, image
fullscreen_button	1: Display the fullscreen button 0: Hide the fullscreen button Default to 1	video, image
timestamp	1: Display the video's current playback time and duration 0: Hide the time info Default to 1	video
loop	1: Play the current video repeatedly 0: Stop the video while it ends Default to 0	video
autoplay	1: Automatically play the video when the player loads 0: Do not start playing automatically Default to 0	video
music_info	1: Display the music info 0: Do not display the music info Default to 0	video, image
description	1: Display the video description 0: Do not display the video description Default to 0	video, image
rel	1: Show recommended videos as related videos 0: Show the current video author's videos as related video Default to 1	video
native_context_menu	1: Display the browser's native context menu 0: Hide the browser's native context menu Default to 1	video, image
closed_caption	1: Display the closed caption icon 0: Hide the closed caption icon Default to 1	video

Message the HTML host

The HTML host communicates with the iframe embedded video page through the Window::postMessage method, where the message body is defined as follows:

interface EmbeddedPlayerMessage<T> {
  'x-tiktok-player': boolean; // Lets you know that this is an embed message.
  value: T;
  type: string; // Defines the message types below. 
}

Host to player messages

Method name (type in EmbeddedPlayerMessage)	Parameter type (value in EmbeddedPlayerMessage)	Value	Post type	Remarks
`play`	void	void	video, image	Use this method to play videos in video posts and to play music in image posts
`pause`	void	void	video, image	Use this method to pause videos in video posts and to pause music in image posts
`seekTo`	number	0–(video length)	video, image	For video posts, use this method to seek the video's time, measured in seconds. For image posts, use this method to seek the music's time, also measured in seconds.
`mute`	void	void	video, image
`unMute`	void	void	video, image
`changeVolume`	number	0–100	video, image	Use this method to adjust the volume to a desired percentage of the maximum volume, measured on a scale of 0 to 100
`navigateTo`	number	0–(number of images -1)	image	Use this method to navigate to the index of the desired image

Player to host messages

Method name (type in EmbedMessage)	Parameter type (value in EmbedMessage)	Value	Post type	Remarks
`onPlayerReady`	void	void	video, image
`onStateChange`	number	-1: init 0: ended 1: playing 2: paused 3: buffering	video, image
`onCurrentTime`	currentTime: number duration: number	0–(video length)	video, image	The current playback time measured in seconds
`onMute`	boolean	True/False	video, image
`onVolumeChange`	number	0–100	video, image	The percentage of the volume relative to the maximum volume measured on a 0–100 scale
`onError`	number	MediaError.code - Web APIs \| MDN	video, image
`onImageChange`	number	0–(number of images -1)	image	The index of the image currently in display

Code example

<html>
<body>

<h1>The iframe element</h1>

<form action="javascript:seekTo(to)">
  <label for="fname">Jump to (seconds)</label><br>
  <input type="text" id="to" name="to" value="20"><br>
</form>

<iframe height="300" width= "400" src="https://www.tiktok.com/player/v1/6718335390845095173?&music_info=1&description=1" allow="fullscreen" title="test"></iframe>
<br />

<script>
  // Receive messages 
        window.addEventListener('message', (event) => {
    // do something
  });

  // Send messages
  function seekTo(to) {
    const iframe = document.querySelector("iframe");
    iframe.contentWindow.postMessage({type: "seekTo", value: Number(to.value), "x-tiktok-player": true}, '*');
  }
</script>

</body>
</html>