View source for Template:Listen image/doc

{{Documentation subpage}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
{{Lua|Module:Infobox|Module:InfoboxImage}}

== Usage ==
{{tl|{{BASEPAGENAME}}}} allows audio files to be embedded in articles with an associated image. It should be used for audio files and their accompanying visual representations that are set off from the text. It is just like {{tl|Listen}}, except that it displays an image above the media player (but in the same box). This gives a much more pleasing visual result than placing a {{tl|Listen}} below an image. 

For [[Wikipedia:Non-free content|non-free, fair-use]] media samples, a description of the media is required to provide contextual significance, and thus satisfy item {{abbr|No.|number}} 8 of the [[Wikipedia:Non-free content criteria#Policy|Policy]] section of [[Wikipedia:Non-free content criteria]]. Do not position non-free audio or video files in the infobox.

===Basic usage===
The audio part of this template is almost exactly the same as {{t|Listen}}. This way, you can convert a {{t|Listen}} to a {{t|Listen image}} by—at the bare minimum—adding the word "image" to the template name and adding the '''main_image''' parameter. 
<pre style="overflow: auto">
{{Listen image
| main_image         =
| main_image_caption =
| main_image_alt     =
| filename           =
| title              =
| description        =
}}
</pre>

* '''main_image''' ''(Required)'': the pagename of the image to display with the audio file, {{em|without}} the <code>File:</code> (formerly <code>Image:</code>) prefix
* '''main_image_caption''': the caption for the main image
* '''main_image_alt ''': the alt text for the main image, for visually impaired readers; see ''[[Wikipedia:Alternative text for images]]''. This is needed for file formats such as [[Ogg]]'s <code>.ogv</code> format that include video as well as sound. The alt text should describe just the initial static image, not the entire video or its sound.
* '''filename''' ''(Required)'': the pagename of the media file, {{em|without}} the <code>File:</code> (formerly <code>Image:</code>) prefix
* '''title''' ''(Required)'': the title of the audio file, to be displayed. Do not use wikilinks in the title – they will not work.
* '''description''': a description of the audio file. For [[Wikipedia:Non-free content|non-free, fair-use]] audio, this must include a textual description of what is heard in the sample.

===Extended usage===
Additional audio files can be embedded in an article with one template by appending a number to each parameter. The maximum number of audio files embedded in this way is ten.

<pre style="overflow: auto">
{{Listen
| main_title         = 
| main_image         = 
| main_image_upright = 
| main_image_size    = 
| main_image_caption = 
| main_image_alt     = 
| filename           = 
| title              = 
| alt                = 
| description        = 
| filename2          = 
| title2             = 
| alt2               = 
| description2       = 
| filename3          = 
| title3             = 
| alt3               = 
| description3       = 
}}
</pre>
* '''main_title''': the title to display, emphasized, at the top of the template. This title applies to the template as a whole. 
* '''main_image''' ''(Required)'': the pagename of the image to display with the audio file, {{em|without}} the <code>File:</code> (formerly <code>Image:</code>) prefix
* '''main_image_upright''': the upright factor, used to scale the main image from its default size. <code>1</code> is the default thumbnail size, <code>2</code> is twice the default thumbnail size, etc. In general, using this parameter should not be necessary, as the image should be appropriately sized for the media player already. See [[Wikipedia:Manual of Style/Images#Size]] for more details. (default value: <code>1.3</code>)
* '''main_image_size''': the image size. In general, using this parameter should not be necessary, as the image should be appropriately sized for the media player already. '''main_image_upright''' is generally preferred to this parameter.  
* '''main_image_caption''': the caption for the main image
* '''filename''' ''(Required)'': the pagename of the media file, ''without'' the File: (formerly Image:) prefix
* '''title''' ''(Required)'': the title of the audio file, to be displayed.
* '''alt''': alt text for the image displayed for the media file, if applicable, for visually impaired readers. 
* '''description''': a description of the audio file

===Style parameters===
The template also takes a number of style parameters to control its appearance:
{{Warning|These style templates all apply to the lower half of this template, containing the audio content, its title, descriptions, etc. They do ''not'' affect the behavior of the upper, image section of the template or the template as a whole. The use cases of some of these parameters are different from the equivalent parameters in {{tl|Listen}}.}}
* '''type''': can be used to alter the image displayed at the left of the audio section depending on the type of audio content being embedded. Acceptable values are '''music''', '''speech''' and '''sound''' (default)
* '''header''': can be used to add a header to the audio content section.
* '''help''': if set to {{para|help|no}}, suppresses the help text that normally appears at the bottom of the audio content section. Only do this if there are other audio files on the page which ''do'' have the help link; it ''must'' be provided on ''at least'' the first file on the article.
* '''image''': define a different image to show to the left of the media player. E.g. {{nowrap|{{para|image|<nowiki>[[File:Example.jps|50px]]</nowiki>}}}}. You can set {{para|image|none}} to disable the image entirely.
* '''start''': Timestamp at which the file should start playing.
* '''style''': can be used to pass specific style instructions to the audio content section. 
* '''embed''': use {{para|embed|yes}} to remove the loudspeaker icon image and padding around the audio content section. 
* '''play''': some media files cannot be displayed inline; if this is the case set {{para|play|no}} to prevent the broken inline link from displaying.
* '''plain''': if set {{para|plain|yes}}, removes most of the ornamentation (image and help links) from the audio content section to give a minimalist version. This also removes the left/right float and positioning, to allow the box to be manually positioned as desired using the {{para|style}} (e.g., {{Para|style|float:right}}) parameter and surrounding markup.


Note: Due to technical limitations, the '''pos''' attribute, which allows you to set the horizontal float of the template in {{t|Listen}}, is not implemented here. This template always floats right. 


===Examples===
'''Basic'''
{{Listen image
| main_image         = Supreme Accordian.jpg
| main_image_caption = An accordion
| main_image_alt     = A black and white accordion
| filename           = Accordion chords-01.ogg
| title              = Accordion chords
| description        = Chords being played on an accordion
}}
<syntaxhighlight lang="wikitext" style="overflow:auto;">
{{Listen image
| main_image         = Supreme Accordian.jpg
| main_image_caption = An accordion
| main_image_alt     = A black and white accordion
| filename           = Accordion chords-01.ogg
| title              = Accordion chords
| description        = Chords being played on an accordion
}}
</syntaxhighlight>
{{-}}

'''Extended'''
{{User:Mysterymanblue/Template:Listen image 2
| main_title         = First piloted lunar mission
| main_image         = Neil Armstrong On The Moon - GPN-2000-001209.jpg
| main_image_upright = 
| main_image_size    = 250px
| main_image_caption = Neil Armstrong on the Moon
| main_image_alt     = A man in a white spacesuit stands faces a spacecraft on a rocky, desolate surface; to his left stands the American flag. 
| header             = Recording of this phrase:
| type               = speech
| filename           = Phrase de Neil Armstrong.oga
| title              = "One small step for a man..."
| description        = First words spoken on the [[Moon]]
}}
<syntaxhighlight lang="wikitext" style="overflow:auto;">
{{User:Mysterymanblue/Template:Listen image 2
| main_title         = First piloted lunar mission
| main_image         = Neil Armstrong On The Moon - GPN-2000-001209.jpg
| main_image_upright = 
| main_image_size    = 250px
| main_image_caption = Neil Armstrong on the Moon
| main_image_alt     = A man in a white spacesuit stands faces a spacecraft on a rocky, desolate surface; to his left stands the American flag. 
| header             = Recording of this phrase:
| type               = speech
| filename           = Phrase de Neil Armstrong.oga
| title              = "One small step for a man..."
| description        = First words spoken on the [[Moon]]
}}
</syntaxhighlight>
{{-}}

'''Multiple files'''
{{Listen image
| main_title         = Second Suite in F
| main_image         = Gustav-Holst-1921.jpg
| main_image_upright = 0.7
| main_image_size    = 
| main_image_caption = Composer [[Gustav Holst]]
| main_image_alt     = A sepia-toned white man in glasses and a suit looks at the viewer. 
| type               = music
| header             = Second Suite in F for Military Band performed by the United States Air Force Heritage of America Band
| filename           = Gustav Holst - Second Suite in F - I. March. Allegro.ogg
| title              = I. March
| alt                = 
| description        = 
| filename2          = Gustav Holst - Second Suite in F - II. Song Without Words "I'll Love My Love".ogg
| title2             = II. Song Without Words "I'll Love My Love"
| alt2               =
| description2       =
| filename3          = Gustav Holst - Second Suite in F - III. Song of the Blacksmith.ogg
| title3             = III. Song of the Blacksmith
| alt3               =
| description3       =
| filename4          = Gustav Holst - Second Suite in F - IV. Fantasia on the "Dargason".ogg
| title4             = IV. Fantasia on the "Dargason"
}}
<syntaxhighlight lang="wikitext" style="overflow:auto;">
{{Listen image
| main_title         = Second Suite in F
| main_image         = Gustav-Holst-1921.jpg
| main_image_upright = 0.7
| main_image_size    = 
| main_image_caption = Composer [[Gustav Holst]]
| main_image_alt     = A sepia-toned white man in glasses and a suit looks at the viewer. 
| type               = music
| header             = Second Suite in F for Military Band performed by the United States Air Force Heritage of America Band
| filename           = Gustav Holst - Second Suite in F - I. March. Allegro.ogg
| title              = I. March
| alt                = 
| description        = 
| filename2          = Gustav Holst - Second Suite in F - II. Song Without Words "I'll Love My Love".ogg
| title2             = II. Song Without Words "I'll Love My Love"
| alt2               =
| description2       =
| filename3          = Gustav Holst - Second Suite in F - III. Song of the Blacksmith.ogg
| title3             = III. Song of the Blacksmith
| alt3               =
| description3       =
| filename4          = Gustav Holst - Second Suite in F - IV. Fantasia on the "Dargason".ogg
| title4             = IV. Fantasia on the "Dargason"
}}
</syntaxhighlight>
{{-}}

'''No listen icon'''
{{Listen image
| main_title         = "Music Masters, Hail to Thee" 
| main_image         = Tri-M Loyalty Song Sheet Music.jpg
| main_image_caption = Sheet music
| main_image_alt     = Two sheets of sheet music entitled "Music Masters, Hail to Thee" lie side by side.
| filename           = Tri-M Loyalty Song.mid
| title              = "Music Masters, Hail to Thee"
| description        = 
| plain              = yes
}}
<syntaxhighlight lang="wikitext" style="overflow:auto;">
{{Listen image
| main_title         = "Music Masters, Hail to Thee" 
| main_image         = Tri-M Loyalty Song Sheet Music.jpg
| main_image_caption = Sheet music
| main_image_alt     = Two sheets of sheet music entitled "Music Masters, Hail to Thee" lie side by side.
| filename           = Tri-M Loyalty Song.mid
| title              = "Music Masters, Hail to Thee"
| description        = 
| plain              = yes
}}
</syntaxhighlight>

===Microformat===
{{UF-audio}}

===See also===
{{Audio templates}}
{{Film- and television-related infobox templates}}

<includeonly>{{Sandbox other||
<!-- Categories go below this line, please; interwikis go to Wikidata, thank you! -->

[[Category:Audio templates]]
[[Category:Embeddable templates]]
}}</includeonly>