---
category: features
---
{@snippet features/build-media-source}
# Media embed
The {@link module:media-embed/mediaembed~MediaEmbed} feature brings support for embeddable media (such as YouTube videos or tweets) in the editor content.
Depending on configuration, it may require using services like [iframely](http://iframe.ly/) or [embed.ly](https://embed.ly/) to display content of these embedded media on your target website. Read more about [displaying embedded media](#displaying-embedded-media-on-your-website).
## Demo
Example URLs:
*
*
*
{@snippet features/media-embed}
## Installation
To add this feature to your editor, install the [`@ckeditor/ckeditor5-media-embed`](https://www.npmjs.com/package/@ckeditor/ckeditor5-media-embed) package:
```bash
npm install --save @ckeditor/ckeditor5-media-embed
```
Then add `'MediaEmbed'` to your plugin list and {@link module:media-embed/mediaembed~MediaEmbedConfig configure} the feature:
```js
import MediaEmbed from '@ckeditor/ckeditor5-media-embed/src/mediaembed';
ClassicEditor
.create( document.querySelector( '#editor' ), {
plugins: [ MediaEmbed, ... ],
toolbar: [ 'mediaEmbed', ... ]
mediaEmbed: {
// configuration...
}
} )
.then( ... )
.catch( ... );
```
## Configuration
### Output type
The data output format of the feature can be configured using the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput `config.mediaEmbed.semanticDataOutput`}:
#### Non–semantic output
TODO (when `false`, default) – outputs media in the same way it works in the editor, i.e. the media preview is saved to the database.
```html
```
##### Semantic output
TODO (when `true`) – does not include the preview of the media, just just the `` tag with the `url` attribute. Best when the application processes (expands) the media on the server–side or directly in the front–end, preserving the versatile database representation.
```html
```
You can easily [expand](#using-media-in-the-frontend) the media using popular embed services in the front–end of your application regardless of the data output type you chose in your database.
### Media providers
CKEditor comes with several supported media providers which can be extended or altered.
Names of providers **with previews**:
* `'dailymotion'`,
* `'spotify'`,
* `'youtube'`,
* `'vimeo'`
Names of providers **without previews**:
* `'instagram'`,
* `'twitter'`,
* `'google'`,
* `'flickr'`,
* `'facebook'`
The default media provider configuration may not support all possible media URLs, only the most common are included.
#### Overriding
To override the default providers, use {@link module:media-embed/mediaembed~MediaEmbedConfig#providers `config.mediaEmbed.providers`} and define your set according to the {@link module:media-embed/mediaembed~MediaEmbedProvider provider syntax}:
```js
ClassicEditor
.create( editorElement, {
plugins: [ MediaEmbed, ... ],
mediaEmbed: {
providers: [
{
name: 'myProvider',
url: /^(https:\/\/)?(www\.)?example\.com\/media\/(\w+)/,
html: mediaId => '...'
},
...
]
}
} )
.then( ... )
.catch( ... );
```
#### Extending
To extend the default list of default providers, use {@link module:media-embed/mediaembed~MediaEmbedConfig#extraProviders `config.mediaEmbed.extraProviders`}.
#### Removing
To remove certain providers, use {@link module:media-embed/mediaembed~MediaEmbedConfig#removeProviders `config.mediaEmbed.premoveProviders`}.
## Displaying embedded media on your website
The media embed feature produces output that may not contain previews of some embedded media. That happens for all media types when the feature is configured to produce a [semantic output](#semantic-output) and for non-previewable media in the default configuration. That means that you need to transform the output `` elements into real media on your target website.
There are many ways to do that. The simplest, plug-and-play solutions are described here. You can also implement this transformation as part of your backend service and you can use different services than described in this section.
### Iframely
[Iframely](https://iframely.com) offers the [embed.js](https://iframely.com/docs/embedjs) library which converts [various media](https://iframely.com/docs/providers) URLs into rich previews. It works in the front–end and remains fully compatible with the output produced by CKEditor.
First, having [secured the API key](https://iframely.com/docs/allow-origins), load the `embed.js` library from the CDN into your website:
```html
...
...
```
#### Semantic data
You can convert all {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput semantic media} like the following Twitter post produced by CKEditor
```html
```
using this short code snippet
```html
```
#### Non–semantic data
Despite including the media preview, the {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput non–semantic} data like the following one
```html
[Media preview]
```
can still be converted by Iframely with just a few extra lines of code. To do that, use a slightly longer code snippet which discards the media preview saved in the database before using `iframely.load()`:
```html
```
### Embedly
Just like Iframely, [Embedly](https://embed.ly) offers the client–side API which converts media URLs into rich previews.
To start using it, load the library from the CDN into your website:
```html
...
...
```
#### Semantic data
You can convert all {@link module:media-embed/mediaembed~MediaEmbedConfig#semanticDataOutput semantic media} like the following Twitter post produced by CKEditor
```html
```
using this code snippet
```html
```
Embedly discovers links like `` and replaces them with rich media previews.
#### Non–semantic data
The code is almost the same as with the semantic data but you should discard the media preview saved in the database before using embedly to avoid code duplication:
```html
```
## Common API
The {@link module:media-embed/mediaembed~MediaEmbed} plugin registers:
* the `'mediaEmbed'` UI button component,
* the `'mediaEmbed'` command implemented by {@link module:media-embed/mediaembedcommand~MediaEmbedCommand}.
You can insert a new media or update the selected media URL by executing the following code:
```js
editor.execute( 'mediaEmbed', { url: 'http://url.to.the/media' } );
```
## Contribute
The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-media-embed.