YouTube Embedded Players and Player Parameters - Google ...

By appending parameters to the IFrame URL, you can customize the playback experience in your application. For example, you can automatically play videos using ... YouTube IFramePlayerAPI Language English BahasaIndonesia Deutsch Español Français Italiano Polski Português–Brasil Türkçe Русский 中文–简体 日本語 한국어 Signin Reference Samples Support YouTube IFramePlayerAPI Reference Samples Support IFrameAPI PlayerParameters MobileAPIs AndroidPlayerAPI iOSHelperLibrary Home Products YouTube IFramePlayerAPI YouTubeEmbeddedPlayersandPlayerParameters Overview ThisdocumentexplainshowtoembedaYouTubeplayerinyourapplicationandalsodefinestheparametersthatareavailableintheYouTubeembeddedplayer. ByappendingparameterstotheIFrameURL,youcancustomizetheplaybackexperienceinyourapplication.Forexample,youcanautomaticallyplayvideosusingtheautoplayparameterorcauseavideotoplayrepeatedlyusingtheloopparameter.YoucanalsousetheenablejsapiparametertoenabletheplayertobecontrolledviatheIFramePlayerAPI. ThispagecurrentlydefinesallparameterssupportedinanyYouTubeembeddedplayer.Eachparameterdefinitionidentifiestheplayersthatsupportthecorrespondingparameter. Note:Embeddedplayersmusthaveaviewportthatisatleast200pxby200px.Iftheplayerdisplayscontrols,itmustbelargeenoughtofullydisplaythecontrolswithoutshrinkingtheviewportbelowtheminimumsize.Werecommend16:9playersbeatleast480pixelswideand270pixelstall. EmbedaYouTubeplayer YoucanuseanyofthefollowingmethodstoembedaYouTubeplayerinyourapplicationandspecifyplayerparameters.Notethattheinstructionsbelowdemonstratehowtoembedaplayerthatloadsasinglevideo.Thefollowingsectionexplainshowtoconfigureyourplayertoloadaplaylistorauser'suploadedvideos. Embedaplayerusingan EmbedaplayerusingtheIFramePlayerAPI FollowtheIFramePlayerAPIinstructionstoinsertavideoplayerinyourwebpageorapplicationafterthePlayerAPI'sJavaScriptcodehasloaded.Thesecondparameterintheconstructorforthevideoplayerisanobjectthatspecifiesplayeroptions.Withinthatobject,theplayerVarspropertyidentifiesplayerparameters. TheHTMLandJavaScriptcodebelowshowsasimpleexamplethatinsertsaYouTubeplayerintothepageelementthathasanidvalueofytplayer.TheonYouTubePlayerAPIReady()functionspecifiedhereiscalledautomaticallywhentheIFramePlayerAPIcodehasloaded.Thiscodedoesnotdefineanyplayerparametersandalsodoesnotdefineothereventhandlers. Selectcontenttoplay Youcanconfigureyourembeddedplayertoloadavideo,aplaylist,orauser'suploadedvideos. Thefollowinglistexplainstheseoptions: Loadingavideo ForanIFrameembed,theYouTubevideoIDforthevideothatyouwanttoloadisspecifiedintheIFrame'ssrcURL. https://www.youtube.com/embed/VIDEO_ID IfyouareusingtheYouTubeDataAPI(v3),youcanprogrammaticallyconstructtheseURLsbyretrievingvideoIDsfromsearchresults,playlistitemresources,videoresources,orotherresources.AfterobtainingavideoID,replacetheVIDEO_IDtextintheURLsabovewiththatvaluetocreatetheplayerURL. Loadingaplaylist SetthelistTypeplayerparametertoplaylist.Inaddition,setthelistplayerparametertotheYouTubeplaylistIDthatyouwanttoload. https://www.youtube.com/embed?listType=playlist&list=PLAYLIST_ID NotethatyouneedtoprependtheplaylistIDwiththelettersPLasshowninthefollowingexample: https://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6 IfyouareusingtheYouTubeDataAPI(v3),youcanprogrammaticallyconstructtheseURLsbyretrievingplaylistIDsfromsearchresults,channelresources,oractivityresources.AfterobtainingaplaylistID,replacethePLAYLIST_IDtextintheURLabovewiththatvalue. Loadingauser'suploadedvideos SetthelistTypeplayerparametertouser_uploads.Inaddition,setthelistplayerparametertotheYouTubeusernamewhoseuploadedvideosyouwanttoload. https://www.youtube.com/embed?listType=user_uploads&list=USERNAME Supportedparameters Allofthefollowingparametersareoptional. Parameters autoplay Thisparameterspecifieswhethertheinitialvideowillautomaticallystarttoplaywhentheplayerloads.Supportedvaluesare0or1.Thedefaultvalueis0. IfyouenableAutoplay,playbackwilloccurwithoutanyuserinteractionwiththeplayer; playbackdatacollectionandsharingwillthereforeoccuruponpageload. cc_lang_pref Thisparameterspecifiesthedefaultlanguagethattheplayerwillusetodisplaycaptions.Settheparameter'svaluetoanISO639-1two-letterlanguagecode.Ifyouusethisparameterandalsosetthecc_load_policyparameterto1,thentheplayerwillshowcaptionsinthespecifiedlanguagewhentheplayerloads.Ifyoudonotalsosetthecc_load_policyparameter,thencaptionswillnotdisplaybydefault,butwilldisplayinthespecifiedlanguageiftheuseroptstoturncaptionson. cc_load_policy Settingtheparameter'svalueto1causesclosedcaptionstobeshownbydefault,eveniftheuserhasturnedcaptionsoff.Thedefaultbehaviorisbasedonuserpreference. color Thisparameterspecifiesthecolorthatwillbeusedintheplayer'svideoprogressbartohighlighttheamountofthevideothattheviewerhasalreadyseen.Validparametervaluesareredandwhite,and,bydefault,theplayerusesthecolorredinthevideoprogressbar.SeetheYouTubeAPIblogformoreinformationaboutcoloroptions.Note:Settingthecolorparametertowhitewilldisablethemodestbrandingoption. controls Thisparameterindicateswhetherthevideoplayercontrolsaredisplayed: controls=0–Playercontrolsdonotdisplayintheplayer. controls=1(default)–Playercontrolsdisplayintheplayer. disablekb Settingtheparameter'svalueto1causestheplayertonotrespondtokeyboardcontrols.Thedefaultvalueis0,whichmeansthatkeyboardcontrolsareenabled.Currentlysupportedkeyboardcontrolsare: Spacebaror[k]:Play/Pause ArrowLeft:Jumpback5secondsinthecurrentvideo ArrowRight:Jumpahead5secondsinthecurrentvideo ArrowUp:Volumeup ArrowDown:VolumeDown [f]:Togglefull-screendisplay [j]:Jumpback10secondsinthecurrentvideo [l]:Jumpahead10secondsinthecurrentvideo [m]:Muteorunmutethevideo [0-9]:Jumptoapointinthevideo.0jumpstothebeginningofthevideo,1jumpstothepoint10%intothevideo,2jumpstothepoint20%intothevideo,andsoforth. enablejsapi Settingtheparameter'svalueto1enablestheplayertobecontrolledviaIFramePlayerAPIcalls.Thedefaultvalueis0,whichmeansthattheplayercannotbecontrolledusingthatAPI.FormoreinformationontheIFrameAPIandhowtouseit,seetheIFrameAPIdocumentation. end Thisparameterspecifiesthetime,measuredinsecondsfromthestartofthevideo,whentheplayershouldstopplayingthevideo.Theparametervalueisapositiveinteger.NotethatthetimeismeasuredfromthebeginningofthevideoandnotfromeitherthevalueofthestartplayerparameterorthestartSecondsparameter,whichisusedinYouTubePlayerAPIfunctionsforloadingorqueueingavideo. fs Settingthisparameterto0preventsthefullscreenbuttonfromdisplayingintheplayer.Thedefaultvalueis1,whichcausesthefullscreenbuttontodisplay. hl Setstheplayer'sinterfacelanguage.TheparametervalueisanISO639-1two-letterlanguagecodeorafullyspecifiedlocale.Forexample,frandfr-caarebothvalidvalues.Otherlanguageinputcodes,suchasIETFlanguagetags(BCP47)mightalsobehandledproperly.Theinterfacelanguageisusedfortooltipsintheplayerandalsoaffectsthedefaultcaptiontrack.NotethatYouTubemightselectadifferentcaptiontracklanguageforaparticularuserbasedontheuser'sindividuallanguagepreferencesandtheavailabilityofcaptiontracks. iv_load_policy Settingtheparameter'svalueto1causesvideoannotationstobeshownbydefault,whereassettingto3causesvideoannotationstonotbeshownbydefault.Thedefaultvalueis1. list Thelistparameter,inconjunctionwiththelistTypeparameter,identifiesthecontentthatwillloadintheplayer. IfthelistTypeparametervalueisuser_uploads,thenthelistparametervalueidentifiestheYouTubechannelwhoseuploadedvideoswillbeloaded. IfthelistTypeparametervalueisplaylist,thenthelistparametervaluespecifiesaYouTubeplaylistID.Intheparametervalue,youneedtoprependtheplaylistIDwiththelettersPLasshownintheexamplebelow. https://www.youtube.com/embed?    listType=playlist    &list=PLC77007E23FF423C6 IfthelistTypeparametervalueissearch,thenthelistparametervaluespecifiesthesearchquery.Note:Thisfunctionalityisdeprecatedandwillnolongerbesupportedasof15November2020. Note:IfyouspecifyvaluesforthelistandlistTypeparameters,theIFrameembedURLdoesnotneedtospecifyavideoID. listType ThelistTypeparameter,inconjunctionwiththelistparameter,identifiesthecontentthatwillloadintheplayer.Validparametervaluesareplaylistanduser_uploads.IfyouspecifyvaluesforthelistandlistTypeparameters,theIFrameembedURLdoesnotneedtospecifyavideoID. Note:Athirdparametervalue,search,hasbeendeprecatedandwillnolongerbesupportedasof15November2020. loop Inthecaseofasinglevideoplayer,asettingof1 causestheplayertoplaytheinitialvideoagainandagain.Inthecaseofaplaylist player(orcustomplayer),theplayerplaystheentireplaylistandthenstartsagainatthe firstvideo. Supportedvaluesare0and 1,andthedefaultvalueis 0.Note:Thisparameterhaslimited supportinIFrameembeds.Toloopasinglevideo,setthe loopparametervalueto1 andsettheplaylistparameter valuetothesamevideoIDalreadyspecifiedinthePlayerAPIURL: https://www.youtube.com/embed/VIDEO_ID?playlist=VIDEO_ID&loop=1 modestbranding ThisparameterletsyouuseaYouTubeplayerthatdoesnotshowaYouTubelogo.Settheparametervalueto1topreventtheYouTubelogofromdisplayinginthecontrolbar.NotethatasmallYouTubetextlabelwillstilldisplayintheupper-rightcornerofapausedvideowhentheuser'smousepointerhoversovertheplayer. origin ThisparameterprovidesanextrasecuritymeasurefortheIFrameAPIandisonlysupportedforIFrameembeds.IfyouareusingtheIFrameAPI,whichmeansyouaresettingtheenablejsapiparametervalueto1,youshouldalwaysspecifyyourdomainastheoriginparametervalue. playlist Thisparameterspecifiesacomma-separatedlistofvideoIDstoplay.Ifyouspecifyavalue,thefirstvideothatplayswillbetheVIDEO_IDspecifiedintheURLpath,andthevideosspecifiedintheplaylistparameterwillplaythereafter. playsinline ThisparametercontrolswhethervideosplayinlineorfullscreenoniOS.Validvaluesare: 0:Resultsinfullscreenplayback.Thisiscurrentlythedefaultvalue,thoughthedefaultissubjecttochange. 1:ResultsininlineplaybackformobilebrowsersandforWebViewscreatedwiththeallowsInlineMediaPlaybackpropertysettoYES. rel Note:ThisparameterischangingonorafterSeptember25,2018. Priortothechange,thisparameterindicateswhethertheplayershouldshowrelatedvideoswhenplaybackoftheinitialvideoends. Iftheparameter'svalueissetto1,whichisthedefaultvalue,thentheplayerdoesshowrelatedvideos. Iftheparameter'svalueissetto0,thentheplayerdoesnotshowrelatedvideos. Afterthechange,youwillnotbeabletodisablerelatedvideos.Instead,iftherelparameterissetto0,relatedvideoswillcomefromthesamechannelasthevideothatwasjustplayed. start Thisparametercausestheplayertobeginplayingthevideoatthegivennumberofsecondsfromthestartofthevideo.Theparametervalueisapositiveinteger.NotethatsimilartotheseekTofunction,theplayerwilllookfortheclosestkeyframetothetimeyouspecify.Thismeansthatsometimestheplayheadmayseektojustbeforetherequestedtime,usuallynomorethanaroundtwoseconds. widget_referrer ThisparameteridentifiestheURLwheretheplayerisembedded.ThisvalueisusedinYouTubeAnalyticsreportingwhentheYouTubeplayerisembeddedinawidget,andthatwidgetisthenembeddedinawebpageorapplication.Inthatscenario,theoriginparameteridentifiesthewidgetprovider'sdomain,butYouTubeAnalyticsshouldnotidentifythewidgetproviderastheactualtrafficsource.Instead,YouTubeAnalyticsusesthewidget_referrerparametervaluetoidentifythedomainassociatedwiththetrafficsource. Revisionhistory April27,2021 Theplaysinlineparameterdefinitionhasbeenupdated slightlytoexplainthattheparameterpertainstobothmobilebrowsersoniOSandiOS WebViews. October15,2020 Theautoplayparameterdefinitionhasbeenupdatedto explainthatifyouenableAutoplay,playbackwilloccurwithoutanyuserinteractionwiththe player;playbackdatacollectionandsharingwillthereforeoccuruponpageload. October13,2020 Note:Thisisadeprecationannouncementfortheembeddedplayer functionalitythatletsyouconfiguretheplayertoloadsearchresults.Thisannouncementaffects theplayer'slistand listTypeparameters. Thischangewillbecomeeffectiveonorafter15November2020.Afterthattime, settingthelistTypeparametervaluetosearchwillgeneratea 4xxresponsecode,suchas404(NotFound)or 410(Gone). Asanalternative,youcanusetheYouTubeDataAPI's search.listmethodtoretrievesearch resultsandthenloadselectedvideosintheplayer. Inadditiontothechangedescribedabove,theshowinfoparameter,whichwas deprecatedin2018,hasbeenremovedfromthisdocument. August23,2018 Note:Thisisadeprecationannouncementfortheshowinfoparameter.Inaddition,thebehaviorfortherelparameterischanging.Titles,channelinformation,andrelatedvideosareanimportantpartofYouTube’scoreuserexperience,andthesechangeshelptomaketheYouTubeviewingexperienceconsistentacrossdifferentplatforms. ThebehaviorfortherelparameterischangingonorafterSeptember25,2018.Theeffectofthechangeisthatyouwillnotbeabletodisablerelatedvideos.However,youwillhavetheoptionofspecifyingthattherelatedvideosshownintheplayershouldbefromthesamechannelasthevideothatwasjustplayed. Tobemorespecific: Priortothechange,iftheparameter'svalueissetto0,thentheplayerdoesnotshowrelatedvideos. Afterthechange,iftherelparameterissetto0,theplayerwillshowrelatedvideosthatarefromthesamechannelasthevideothatwasjustplayed. Theshowinfoparameter,whichindicateswhethertheplayershoulddisplayinformationlikethevideotitleanduploaderbeforethevideostartsplaying,isalsobeingdeprecated.Followingthechange,thechannelavatarandvideotitlewillalwaysdisplaybeforeplaybackbegins,whenplaybackispaused,andwhenplaybackends.Theavatarbeingdisplayedisnewbehaviorthatwillbeconsistentacrossallembeddedplayers. ThesechangeswillbecomeeffectiveonorafterSeptember25,2018.Afterthattime,theshowinfoparameterwillbeignored.Thebehaviorfollowingthechangesisconsistentwiththecurrentdefaultbehaviorforembeddedplayerswiththeexceptionofthechannelavatarchangesmentionedabove. August16,2018 Thecc_lang_prefparametercanbeusedtospecifythedefaultlanguagethattheplayerwillusetodisplaycaptions.Thisparametercanbeusedinconjunctionwiththecc_load_policyparametertoautomaticallyshowcaptionsinthespecifiedlanguageduringplayback. September15,2017 Thecontrolsparameter'sdefinitionhasbeenupdatedtoremovereferencestothedeprecatedFlash(AS3)player.Thevalue2hasbeendeprecatedasitwasoriginallydesignedtoprovideaperformanceimprovementforembedsthatloadedaFlashplayer. June12,2017 Thenewwidget_referrerparameterhelpstoenablemoreaccurateYouTubeAnalyticsreportingwhentheYouTubeplayerisembeddedinawidget,andthatwidgetisthenembeddedinawebpageorapplication. November1,2016 ThisdocumenthasbeenupdatedtoremovereferencestothedeprecatedFlash(AS3)playeraswellastoparametersonlysupportedbythatplayer.TheYouTubeFlashplayerwasdeprecatedinJanuary2015. October20,2016 Thisupdatecontainsthefollowingchanges: Thedisablekbparameterdefinitionhasbeencorrectedtonotethatthedefaultvalueis0,whichmeansthatkeyboardcontrolsareenabled.Avalueof1indicatesthatkeyboardcontrolsshouldbedisabled. Thelistofkeyboardcontrolsthattheplayersupportshasalsobeenupdatedtoincludethefollowing: [f]:Togglefull-screendisplay [j]:Jumpback10secondsinthecurrentvideo [k]:Play/Pause [l]:Jumpahead10secondsinthecurrentvideo [m]:Muteorunmutethevideo [0-9]:Jumptoapointinthevideo.0jumpstothebeginningofthevideo,1jumpstothetime10%intothevideo,2jumpstothepoint20%intothevideo,andsoforth. Inaddition,theeffectofpressingthe[arrowleft]or[arrowright]keyshaschanged.Thesekeysnowjump5secondsback(arrowleft)orahead(arrowright)inthecurrentvideo. August11,2016 Thisupdatecontainsthefollowingchanges: ThenewlypublishedYouTubeAPIServicesTermsofService("theUpdatedTerms"),discussedindetailontheYouTubeEngineeringandDevelopersBlog,providesarichsetofupdatestothecurrentTermsofService.InadditiontotheUpdatedTerms,whichwillgointoeffectasofFebruary10,2017,thisupdateincludesseveralsupportingdocumentstohelpexplainthepoliciesthatdevelopersmustfollow. ThefullsetofnewdocumentsisdescribedintherevisionhistoryfortheUpdatedTerms.Inaddition,futurechangestotheUpdatedTermsortothosesupportingdocumentswillalsobeexplainedinthatrevisionhistory.YoucansubscribetoanRSSfeedlistingchangesinthatrevisionhistoryfromalinkinthatdocument. December18,2015 EuropeanUnion(EU)lawsrequirethatcertaindisclosuresmustbegiventoandconsentsobtainedfromendusersintheEU.Therefore,forendusersintheEuropeanUnion,youmustcomplywiththeEUUserConsentPolicy.WehaveaddedanoticeofthisrequirementinourYouTubeAPITermsofService. August19,2015 TheautohideparameterhasbeendeprecatedfortheHTML5player.InHTML5players,thevideoprogressbarandplayercontrolsdisplayorhideautomatically.Thatbehaviorcorrespondstoanautohidesettingof1. ThethemeparameterhasbeendeprecatedfortheHTML5player.HTML5playersnowalwaysusethedarktheme. March9,2015 ThedocumenthasbeenupdatedtoreflectthefactthatYouTube