OEmbedPlugin

Easy embedding of third party content

oEmbed is a format for enabling an embedded representation of a URL on third party websites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

All you need to do to embed material from one of the supported providers is add a link to it. The plugin will contact the provider and use the appropriate code to add it to the page, e.g. an iframe for videos and the like.

Supported providers

1. 23HQ
2. Abraia
3. ActBlue
4. Adilo
5. Adways
6. AltiumLLC
7. Altru
8. Amtraker
9. Animatron
10. Animoto
11. AnnieMusic
12. Apester
13. ArcGISStoryMaps
14. Archivos
15. AudioClip
16. Audioboom
17. Audiomack
18. Audiomeans
19. Avocode
20. Backtracks
21. Beautiful.AI
22. Blackfire.io
23. Blogcast
24. Bookingmood
25. BoxOfficeBuz
26. BrioVR
27. Bumper
28. Buttondown
29. ByzartProject
30. CHROCO
31. Cacoo
32. CatBoat
33. Catapult
34. Ceros
35. Chainflix
36. ChartBlocks
37. CircuitLab
38. Clipland
39. Clyp
40. CoCoCorp
41. CodeHS
42. CodePen
43. CodeSandbox
44. Codepoints
45. CollegeHumor
46. Commaful
47. Coub
48. CrowdRanking
49. Crumb.sh
50. CueupDJBooking
51. Curated
52. CustomerDB
53. DALEXNI
54. DTube
55. Dailymotion
56. Datawrapper
57. DeseretNews
58. Deviantart.com
59. Didacte
60. Digiteka
61. DocDroid
62. Dotsub
63. EgliseInfo
64. Embedery
65. Embedly
66. EnystreMusic
67. Ethfiddle
68. EventLive
69. Ex.Co
70. Eyrie
71. FITE
72. FOXSPORTSAustralia
73. Facebook
74. Fader
75. FaithlifeTV
76. Firework
77. Flat
78. Flickr
79. Flourish
80. FrameBuzz
81. Framer
82. GIPHY
83. GMetri
84. GTChannel
85. GeographBritainandIreland
86. GeographChannelIslands
87. GeographGermany
88. GettyImages
89. Gfycat
90. Gifnote
91. GloriaTV
92. Gong
93. Grain
94. Gyazo
95. HASH
96. HippoVideo
97. Homey
98. HuffDuffer
99. Hulu
100. IFTTT
101. Idomoo
102. Incredible
103. Indaco
104. Infogram
105. Infoveave
106. Injurymap
107. Inoreader
108. Instagram
109. InsticatorInc
110. Issuu
111. Jovian
112. KakaoTv
113. Kickstarter
114. Kidoju
115. Kirim.Email
116. Kit
117. Kitchenbowl
118. Knacki
119. KnowledgePad
120. Kooapp
121. LeMans.Pod
122. LearningApps.org
123. Lille.Pod
124. Livestream
125. LottieFiles
126. Ludus
127. Lumiere
128. MathEmbed
129. Matterport
130. MediaLab
131. MedienarchivderKünste-ZürcherHochschulederKünste
132. MermaidInk
133. MicrosoftStream
134. Minerva
135. MixCloud
136. MobyPicture
137. MusicBoxManiacs
138. NFTNDX.IO
139. Namchey
140. Nasjonalbiblioteket
141. NaturalAtlas
142. NoPaste
143. OZ
144. Observable
145. Odds.com.au
146. Odesli(formerlySonglink)
147. Odysee
148. OfficialFM
149. Omniscope
150. OmnyStudio
151. OraTV
152. Orbitvu
153. Outplayed.tv
154. Overflow
155. Padlet
156. PandaVideo
157. Pastery
158. PingVP
159. Pinpoll
160. Pinterest
161. PitchHub
162. Pixdor
163. Podbean
164. PollDaddy
165. Portfolium
166. Present
167. PreziVideo
168. Quiz.biz
169. Quizz.biz
170. RadioPublic
171. Raindrop
172. Reddit
173. ReleaseWire
174. Replit
175. ReverbNation
176. Roomshare
177. RoosterTeeth
178. Rumble
179. Runkit
180. Saooti
181. SapoVideos
182. Screen9
183. Screencast.com
184. Screenr
185. ScribbleMaps
186. Scribd
187. SendtoNews
188. ShortNote
189. Shoudio
190. ShowbyAnimaker
191. ShowtheWay,actionablelocationinfo
192. Simplecast
193. Sizzle
194. Sketchfab
195. SlideShare
196. SmashNotes
197. Smrthi
198. SmugMug
199. SocialExplorer
200. SoundCloud
201. SpeakerDeck
202. Spotify
203. Spreaker
204. SproutVideo
205. StanfordDigitalRepository
206. Streamable
207. Streamio
208. Subscribi
209. Sudomemo
210. Sutori
211. Sway
212. SwayOffice
213. Synthesia
214. TED
215. TheNewYorkTimes
216. TheySaidSo
217. TickCounter
218. TikTok
219. Toornament
220. Topy
221. Totango
222. TrinityAudio
223. Tumblr
224. Tuxx
225. Twitter
226. TypeCast
227. Typlog
228. UAPod
229. UnivParis1.Pod
230. UniversityofCambridgeMap
231. Upec.Pod
232. Ustream
233. VEVO
234. VLIVE
235. VeeRVR
236. Verse
237. Videfit
238. Vidyard
239. Vimeo
240. Viously
241. Vizydrop
242. Vlipsy
243. Vouch
244. VoxSnap
245. Waltrack
246. Wave.video
247. Wiredrive
248. Wistia,Inc.
249. Wokwi
250. WolframCloud
251. WordPress.com
252. YouTube
253. Zeplin
254. ZingSoft
255. ZnipeTV
256. Zoomable
257. afreecaTV
258. amChartsLiveEditor
259. chirbit.com
260. dadan
261. eduMedia
262. everviz
263. hearthis.at
264. hihaho
265. iFixit
266. iHeartRadio
267. inphood
268. kmdr
269. me.me
270. myBeweeg
271. nanoo.tv
272. nfb.ca
273. rcvis
274. tvcf
275. uStudio,Inc.
276. wecandeo
277. wizer.me

A lot of providers are available via http://embed.ly. However, you'll have to register to get an api-key. Some of the listed providers have already been added to this plugin, yet not all.

Syntax

EMBED

%EMBED{"url" [width="..." height="..."]}% (or %OEMBED{...}%)

• url: an external link to the resource to be embedded
• width, height: optional maximum values for the image/video/... being embedded (note: not all providers properly implement these parameters)
• format: a format string to implement a custom renderer
• template: the name of a template defined in oembed.tmpl; known templates shipped with OEmbedPlugin are "article" (todo add more)
• quality (youtube only): specify the thumbnail quality; possible values are hq, mq, sd, default and auto; the latter will find out automatically which best thumbnail is available
• <custom_key>: any custom key="value" pair may be defined and made use of in the format (or template) using $custom_key to expand it; these have higher precendence than the default values submitted by the oembed provider; for example use a custom thumbnail_width="100" parameter to override the default width.

The keys in the json submitted from the oembed provider can be used in a format string (or a template definition). Some well-known keys are:

• $author_name
• $author_url
• $descriptio
• $html
• $provider_name
• $provider_url
• $thumbnail_height
• $thumbnail_url
• $thumbnail_width
• $title
• $type
• $url
• $web_page

In addition all standard format tokens can be used ($percnt, $dollar, $nop, etc).

See the oembed.tmpl file on how to use them.

OEMBED_PROVIDER

%OEMBED_PROVIDER{["<id>"]}%

• id: provider name to display the configuration for
• format: format string, defaults to    1 [[$provider][$name]
• header: header string added if there was a provider in the list
• footer: footer string added if ...
• separator: separator string inserted between each provider found
• exampleformat: format strings for available examples
• exampleheader
• examplefooter
• exampleseparator
• include: regular expression that the provider must match to be included in the output
• exclude: regular expression that the provider must not match to be included in the output

The format string may use the following variables

• $name: name of provider
• $examples: example string constructed from example[format,header,footer,separator]
• $provider: url address of the provider
• $api: api address for the oembed endpoint
• $url: list of patterns that an url must match to be processed by this provider

To display all examples stored in the provider records use:

<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%">
*Url*: 
<input type="text" size="80" name="url" value="%URLPARAM{"url"}%" />
<input type="submit" class="foswikiButton" value="Embed" />
</form>

%IF{"$'URLPARAM{url}'!=''"
  then="$percntEMBED{\"%URLPARAM{"url"}%\"}$percnt"
}%

%OEMBED_PROVIDER{
   format="   1 $name: $examples"
   exampleformat="[[%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%?url=$url][example]]"
}%

Examples

Youbtube

%EMBED{"https://www.youtube.com/watch?v=O8e8Ttfz-pY" width="600"}%

%EMBED{"https://www.youtube.com/watch?v=O8e8Ttfz-pY" width="600"}%

Soundcloud

%EMBED{"https://soundcloud.com/safia-music/listen-to-soul-listen-to-blues" width="600"}%

%EMBED{"https://soundcloud.com/safia-music/listen-to-soul-listen-to-blues" width="600"}%

Flickr

%EMBED{"https://www.flickr.com/photos/onement/1239189689/" height="400"}%

%EMBED{"https://www.flickr.com/photos/onement/1239189689/" height="400"}%

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Moo	>=0	Required
Regexp::Assemble	>=0	Required
Foswiki::Contrib::CacheContrib	>=0	Required

Change History

30 Apr 2024	fixed use of CacheContrib
30 May 2023	fixed parsing video id from youtube iframes
05 May 2022	added a few more oembed providers
03 Mar 2021	adedd microsoft stream provider
22 Jan 2020	imported provider from https://github.com/iamcal/oembed; implemented %OEMBED_PROVIDER
13 Mar 2019	document quality parameter when embeding youtube videos; added quality="auto" to fetch the best thumbnail available; added support for proxy
25 Sep 2017	added clearCache REST interface for local cache maintenance
17 Nov 2016	more providers; converted Web::oEmbed from Any::Moose to Moo
07 Oct 2015	multiple providers went in & out
16 Mar 2015	added Infogram
23 Feb 2015	added a few more provider
16 Dec 2014	have an image preview for vimeo and youtube and only embed the real video when clicking on it; added Vine
25 Sep 2014	added caching
24 Sep 2014	added a custom renderer for youtube videos
29 Aug 2014	removed my opera, qirk and urtak; use https whereever possible
01 Nov 2013	added more providers
30 Aug 2013	added more providers
24 Jun 2013	added format, template and custom params; added a few more providers