001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.bean.html5;
018
019import java.net.*;
020
021import org.apache.juneau.marshall.*;
022
023/**
024 * DTO for an HTML <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#the-audio-element">&lt;audio&gt;</a>
025 * element.
026 *
027 * <p>
028 * The audio element embeds sound content in documents. It can contain audio streams, audio files,
029 * or other audio sources. The browser will choose the most appropriate source based on format
030 * support and user preferences.
031 *
032 * <h5 class='section'>Examples:</h5>
033 * <p class='bcode w800'>
034 *    <jc>// Simple audio with single source</jc>
035 *    Audio <jv>audio1</jv> = <jsm>audio</jsm>().src(<js>"audio.mp3"</js>).controls(<jk>true</jk>);
036 *
037 *    <jc>// Audio with multiple sources for browser compatibility</jc>
038 *    Audio <jv>audio2</jv> = <jsm>audio</jsm>().controls(<jk>true</jk>)
039 *       .children(
040 *          <jsm>source</jsm>().src(<js>"audio.mp3"</js>).type(<js>"audio/mpeg"</js>),
041 *          <jsm>source</jsm>().src(<js>"audio.ogg"</js>).type(<js>"audio/ogg"</js>)
042 *       );
043 *
044 *    <jc>// Autoplay audio with loop</jc>
045 *    Audio <jv>audio3</jv> = <jsm>audio</jsm>().src(<js>"background.mp3"</js>).autoplay(<jk>true</jk>).loop(<jk>true</jk>).muted(<jk>true</jk>);
046 * </p>
047 *
048 * <p>
049 * The following convenience methods are provided for constructing instances of this bean:
050 * <ul class='javatree'>
051 *    <li class='jc'>{@link HtmlBuilder}
052 *    <ul class='javatree'>
053 *       <li class='jm'>{@link HtmlBuilder#audio() audio()}
054 *       <li class='jm'>{@link HtmlBuilder#audio(String) audio(String)}
055 *    </ul>
056 * </ul>
057 * </p>
058 *
059 * <h5 class='section'>See Also:</h5><ul>
060 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
061 * </ul>
062 */
063@Marshalled(typeName = "audio")
064public class Audio extends HtmlElementMixed<Audio> {
065
066   /**
067    * Creates an empty {@link Audio} element.
068    */
069   public Audio() {}
070
071   /**
072    * Creates an {@link Audio} element with the specified {@link Audio#src(Object)} attribute.
073    *
074    * @param src The {@link Audio#src(Object)} attribute. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed).
075    */
076   public Audio(String src) {
077      src(src);
078   }
079
080   /**
081    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-autoplay">autoplay</a>
082    * attribute.
083    *
084    * <p>
085    * Hint that the media resource can be started automatically when the page is loaded.
086    *
087    * <p>
088    * This attribute uses deminimized values:
089    * <ul>
090    *    <li><jk>false</jk> - Attribute is not added</li>
091    *    <li><jk>true</jk> - Attribute is added as <js>"autoplay"</js></li>
092    *    <li>Other values - Passed through as-is</li>
093    * </ul>
094    *
095    * @param value
096    *    The new value for this attribute.
097    *    Typically a {@link Boolean} or {@link String}.
098    *    Can be <jk>null</jk> to unset the attribute.
099    * @return This object.
100    */
101   public Audio autoplay(Object value) {
102      attr("autoplay", deminimize(value, "autoplay"));
103      return this;
104   }
105
106   /**
107    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-controls">controls</a>
108    * attribute.
109    *
110    * <p>
111    * Show user agent controls.
112    *
113    * <p>
114    * This attribute uses deminimized values:
115    * <ul>
116    *    <li><jk>false</jk> - Attribute is not added</li>
117    *    <li><jk>true</jk> - Attribute is added as <js>"controls"</js></li>
118    *    <li>Other values - Passed through as-is</li>
119    * </ul>
120    *
121    * @param value
122    *    The new value for this attribute.
123    *    Typically a {@link Boolean} or {@link String}.
124    *    Can be <jk>null</jk> to unset the attribute.
125    * @return This object.
126    */
127   public Audio controls(Object value) {
128      attr("controls", deminimize(value, "controls"));
129      return this;
130   }
131
132   /**
133    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-crossorigin">crossorigin</a>
134    * attribute.
135    *
136    * <p>
137    * Specifies how the element handles cross-origin requests for CORS (Cross-Origin Resource Sharing).
138    *
139    * <p>
140    * Possible values:
141    * <ul>
142    *    <li><js>"anonymous"</js> - Cross-origin requests are made without credentials</li>
143    *    <li><js>"use-credentials"</js> - Cross-origin requests include credentials</li>
144    * </ul>
145    *
146    * @param value How to handle cross-origin requests. Can be <jk>null</jk> to unset the attribute.
147    * @return This object.
148    */
149   public Audio crossorigin(String value) {
150      attr("crossorigin", value);
151      return this;
152   }
153
154   /**
155    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-loop">loop</a> attribute.
156    *
157    * <p>
158    * Causes the media to automatically restart from the beginning when it reaches the end.
159    *
160    * @param value If <jk>true</jk>, the media will loop continuously. Can be <jk>null</jk> to unset the attribute.
161    * @return This object.
162    */
163   public Audio loop(Object value) {
164      attr("loop", value);
165      return this;
166   }
167
168   /**
169    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-mediagroup">mediagroup</a>
170    * attribute.
171    *
172    * <p>
173    * Groups multiple media elements together so they can be controlled as a single unit. All media elements
174    * with the same mediagroup value will share the same MediaController, allowing synchronized playback.
175    *
176    * <p>
177    * This is useful for creating synchronized audio/video presentations or multiple audio tracks.
178    *
179    * @param value The name of the media group to join. Can be <jk>null</jk> to unset the attribute.
180    * @return This object.
181    */
182   public Audio mediagroup(String value) {
183      attr("mediagroup", value);
184      return this;
185   }
186
187   /**
188    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-muted">muted</a>
189    * attribute.
190    *
191    * <p>
192    * Mutes the audio output by default. Useful for autoplay videos where audio should be disabled initially.
193    *
194    * @param value If <jk>true</jk>, the media will be muted by default. Can be <jk>null</jk> to unset the attribute.
195    * @return This object.
196    */
197   public Audio muted(Object value) {
198      attr("muted", value);
199      return this;
200   }
201
202   /**
203    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-preload">preload</a>
204    * attribute.
205    *
206    * <p>
207    * Specifies how the browser should load the media resource.
208    *
209    * <p>
210    * Possible values:
211    * <ul>
212    *    <li><js>"none"</js> - Do not preload the media</li>
213    *    <li><js>"metadata"</js> - Preload only metadata (duration, dimensions, etc.)</li>
214    *    <li><js>"auto"</js> - Preload the entire media file (default)</li>
215    * </ul>
216    *
217    * @param value How much of the media to preload. Can be <jk>null</jk> to unset the attribute.
218    * @return This object.
219    */
220   public Audio preload(Object value) {
221      attr("preload", value);
222      return this;
223   }
224
225   /**
226    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-src">src</a> attribute.
227    *
228    * <p>
229    * Address of the resource.
230    *
231    * <p>
232    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
233    * Strings must be valid URIs.
234    *
235    * <p>
236    * URIs defined by {@link UriResolver} can be used for values.
237    *
238    * @param value
239    *    The new value for this attribute.
240    *    Typically a {@link URL} or {@link String}.
241    *    Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed).
242    * @return This object.
243    */
244   public Audio src(Object value) {
245      attrUri("src", value);
246      return this;
247   }
248
249}