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 * <h2 class='section'>Examples:</h2>
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 *
058 * <h2 class='section'>See Also:</h2><ul>
059 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a>
060 * </ul>
061 */
062@Marshalled(typeName = "audio")
063public class Audio extends HtmlElementMixed<Audio> {
064
065   /**
066    * Creates an empty {@link Audio} element.
067    */
068   public Audio() {}
069
070   /**
071    * Creates an {@link Audio} element with the specified {@link Audio#src(Object)} attribute.
072    *
073    * @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).
074    */
075   public Audio(String src) {
076      src(src);
077   }
078
079   /**
080    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-autoplay">autoplay</a>
081    * attribute.
082    *
083    * <p>
084    * Hint that the media resource can be started automatically when the page is loaded.
085    *
086    * <p>
087    * This attribute uses deminimized values:
088    * <ul>
089    *    <li><jk>false</jk> - Attribute is not added</li>
090    *    <li><jk>true</jk> - Attribute is added as <js>"autoplay"</js></li>
091    *    <li>Other values - Passed through as-is</li>
092    * </ul>
093    *
094    * @param value
095    *    The new value for this attribute.
096    *    Typically a {@link Boolean} or {@link String}.
097    *    Can be <jk>null</jk> to unset the attribute.
098    * @return This object.
099    */
100   public Audio autoplay(Object value) {
101      attr("autoplay", deminimize(value, "autoplay"));
102      return this;
103   }
104
105   /**
106    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-controls">controls</a>
107    * attribute.
108    *
109    * <p>
110    * Show user agent controls.
111    *
112    * <p>
113    * This attribute uses deminimized values:
114    * <ul>
115    *    <li><jk>false</jk> - Attribute is not added</li>
116    *    <li><jk>true</jk> - Attribute is added as <js>"controls"</js></li>
117    *    <li>Other values - Passed through as-is</li>
118    * </ul>
119    *
120    * @param value
121    *    The new value for this attribute.
122    *    Typically a {@link Boolean} or {@link String}.
123    *    Can be <jk>null</jk> to unset the attribute.
124    * @return This object.
125    */
126   public Audio controls(Object value) {
127      attr("controls", deminimize(value, "controls"));
128      return this;
129   }
130
131   /**
132    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-crossorigin">crossorigin</a>
133    * attribute.
134    *
135    * <p>
136    * Specifies how the element handles cross-origin requests for CORS (Cross-Origin Resource Sharing).
137    *
138    * <p>
139    * Possible values:
140    * <ul>
141    *    <li><js>"anonymous"</js> - Cross-origin requests are made without credentials</li>
142    *    <li><js>"use-credentials"</js> - Cross-origin requests include credentials</li>
143    * </ul>
144    *
145    * @param value How to handle cross-origin requests. Can be <jk>null</jk> to unset the attribute.
146    * @return This object.
147    */
148   public Audio crossorigin(String value) {
149      attr("crossorigin", value);
150      return this;
151   }
152
153   /**
154    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-loop">loop</a> attribute.
155    *
156    * <p>
157    * Causes the media to automatically restart from the beginning when it reaches the end.
158    *
159    * @param value If <jk>true</jk>, the media will loop continuously. Can be <jk>null</jk> to unset the attribute.
160    * @return This object.
161    */
162   public Audio loop(Object value) {
163      attr("loop", value);
164      return this;
165   }
166
167   /**
168    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-mediagroup">mediagroup</a>
169    * attribute.
170    *
171    * <p>
172    * Groups multiple media elements together so they can be controlled as a single unit. All media elements
173    * with the same mediagroup value will share the same MediaController, allowing synchronized playback.
174    *
175    * <p>
176    * This is useful for creating synchronized audio/video presentations or multiple audio tracks.
177    *
178    * @param value The name of the media group to join. Can be <jk>null</jk> to unset the attribute.
179    * @return This object.
180    */
181   public Audio mediagroup(String value) {
182      attr("mediagroup", value);
183      return this;
184   }
185
186   /**
187    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-muted">muted</a>
188    * attribute.
189    *
190    * <p>
191    * Mutes the audio output by default. Useful for autoplay videos where audio should be disabled initially.
192    *
193    * @param value If <jk>true</jk>, the media will be muted by default. Can be <jk>null</jk> to unset the attribute.
194    * @return This object.
195    */
196   public Audio muted(Object value) {
197      attr("muted", value);
198      return this;
199   }
200
201   /**
202    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-preload">preload</a>
203    * attribute.
204    *
205    * <p>
206    * Specifies how the browser should load the media resource.
207    *
208    * <p>
209    * Possible values:
210    * <ul>
211    *    <li><js>"none"</js> - Do not preload the media</li>
212    *    <li><js>"metadata"</js> - Preload only metadata (duration, dimensions, etc.)</li>
213    *    <li><js>"auto"</js> - Preload the entire media file (default)</li>
214    * </ul>
215    *
216    * @param value How much of the media to preload. Can be <jk>null</jk> to unset the attribute.
217    * @return This object.
218    */
219   public Audio preload(Object value) {
220      attr("preload", value);
221      return this;
222   }
223
224   /**
225    * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-media-src">src</a> attribute.
226    *
227    * <p>
228    * Address of the resource.
229    *
230    * <p>
231    * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
232    * Strings must be valid URIs.
233    *
234    * <p>
235    * URIs defined by {@link UriResolver} can be used for values.
236    *
237    * @param value
238    *    The new value for this attribute.
239    *    Typically a {@link URL} or {@link String}.
240    *    Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed).
241    * @return This object.
242    */
243   public Audio src(Object value) {
244      attrUri("src", value);
245      return this;
246   }
247
248}