View source for Looping a sound

{{lang|Looping a sound}}
{{subpage|[[Sound and Music]]}}
{{toc-right}}

A looped sound will repeat endlessly without any gap between its end and start. It is up to the sound artist to ensure that the end and start of the file match up however, or there will be a "pop" as the waveform jumps from one shape to another.

'''{{gldsrc|4}} and {{Src|4}} detect looped sounds ONLY through cue points embedded in the file.''' This is a [[WAV]]-only feature, so [[MP3]]s cannot be looped. Microsoft ADPCM compressed WAVs can be looped, but due to the way they are encoded, there may a pop when the sound restarts if the sound is shorter than a few seconds.
{{note|{{src2|4}} supports looping both [[WAV]] and [[MP3]], but only {{sbox|4|addtext='s}} tools can set the looping flag in a [[VSND]] for MP3 files; first-party Valve tools still rely upon [[WAV]] cues points to determine when a [[VSND]] should loop.}}
{{modernFix|With custom audio backends, it is theoretically possible to loop filetypes other than WAV. Compressed audio formats usually have a small decoding delay upon restarting a track, which can appear as a small pop or stutter, with MP3 being worse due to its fixed frame size and Ogg Vorbis being the cleanest. [http://www.compuphase.com/mp3/mp3loops.htm This can theoretically be avoided for any compressed format, including MP3.]}}

{{note|There is no need to mark a sound as looping when playing it, but if using [[ambient_generic]] you will find that the "Is NOT Looped" flag must be set correctly if you want to stop the sound after it starts!}}

{{warning|{{l4d2}} During development: editing the contents of an existing sound file stored in your campaign's ''sound.cache'' will not show any change until the sound cache is rebuilt! See [[L4D2 Campaign Add-on Tutorial#Creating a sound.cache files|Creating a sound.cache file]] or [[L4D2 Custom Sound and Music Tutorial]] for further instructions.}}

{{todo|Remove stuff regarding end loop points; they don't work in any engine, and can prevent the sound from looping in {{goldsrc|2}}.}}

== Looping a WAV ==

These free programs can add cue points to a WAV:

* [http://www.goldwave.com/ GoldWave] (trialware)
* [http://www.wavosaur.com/ Wavosaur] (freeware)
* [https://loopauditioneer.sourceforge.io/ LoopAuditioneer] (free and open source)
* [https://www.ocenaudio.com/ OcenAudio] (freeware)

=== GoldWave ===

Open Goldwave and open the sound you want to loop. Click the '''cues''' icon. ([[File:Cues button.jpg]])
Then in the new window click on the '''New''' button and add a cue point '''At Start'''. Then click '''New''' for another cue point and add a point '''At End'''. So it looks similar to this:

[[File:Cue dialog.jpg]]

=== Wavosaur ===

{{warning|{{gldsrc|4}} doesn't use Wavosaur's loop points. Instead, the start cue is actually the first marker (M0).}}
{{warning|{{Source|4}} supports both Wavosaur's loop points and markers for looping a sound but will prioritize markers over loop points if both are present. Because of this, and because end points are unused, markers may be preferred for compatibility.}}
{{warning|End cue points are unused. You should trim the file instead.}}
{{todo|Do loop points work in {{Portal 2|4}}? The marker route was initially added to the page due to the loop points being reported as non-functional in that game.}}

==== Looping from beginning to end ====

* Open Wavosaur.
* Open the sound you want to loop.
* Go to <code>Tools > Markers > Create marker</code>, or press {{key|M}}. This will add a new M0 marker at the beginning.
** If the marker is not at the beginning, move it there by dragging it with the mouse.

After that, click "Save" or "Save As".

==== Looping from anywhere in the file ====

# Open Wavosaur.
# Open the sound you want to loop.
# Go to <code>Tools > Loop > Create loop points</code>. It should create loop points.
## You can change their positions by dragging them.
## If you're looping a sound for {{src|bold}}, the end point should be moved at the end of the track, as end cues are not functional (see the [[Talk:Looping_a_Sound|Discussion]] page). You should trim the end instead.
## Double-clicking between the loop points will select the whole region between them and allow you to play it on loop.

Once you have found a satisfying position for the starting point:

# Click outside of the selection to clear it.
# Double-click the area between the loop points to select it.
## Do NOT play it now! Wavosaur uses the "playing position" to create markers.
# Go to <code>Tools > Markers > Create marker</code>, or press {{key|M}}. This will add a new M0 marker at the exact position of the loop's starting point.
# Go to <code>Tools > Loop > Delete loop points</code> to clean up the unnecessary data. Failure to do so is inconsequential in Source, but will result in the track not looping in GoldSrc. 

After that, click "Save" or "Save As".

{{warning|Wavosaur does not support ADPCM-compressed WAV files; attempting to open one will result in the application crashing!}}

=== With a hex editor or script ===
{| class=wikitable style="float:right; margin:0 1em"
|+ style=color:#bbb| Bytes of a [https://www.recordingblogs.com/wiki/cue-chunk-of-a-wave-file Cue Chunk] of a WAV file
! Bytes ([[w:Hexadecimal|hex]]) !! as [[w:ASCII#Character_set|ASCII]] !! as [[w:Endianness|Little<br>Endian]]<br>Integer !! Description
|-
| <code>63 75 65 20</code> || <code>"cue "</code> || || begins a new cue chunk
|-
| <code>1C 00 00 00</code> || || <code>24</code> || size of this cue chunk in bytes<br>(= the number of bytes that follow)
|-
| <code>01 00 00 00</code> || || <code>1</code> || number of cue points that follow now
|-
| || || ||
|-
| <code>01 00 00 00</code> || || <code>1</code> || ID of first (and only) cue point
|-
| <code>00 00 00 00</code> || || <code>0</code> || ''position''<br>(Wavosaur uses this as the cue point position)
|-
| <code>64 61 74 61</code> || <code>"data"</code> || || what kind of chunk this first cue point lies in
|-
| <code>00 00 00 00</code> || || <code>0</code> || ''chunk start''
|-
| <code>00 00 00 00</code> || || <code>0</code> || ''block start''
|-
| <code>00 00 00 00</code> || || <code>0</code> || sample position that Source uses to loop
|}
Appending the following bytes to the end of a non-looping [[WAV]] file will make it loop in its entirety. These bytes represent a cue chunk that defines a cue point at the very first sample:
<pre><nowiki>63 75 65 20 1C 00 00 00 01 00 00 00 01 00 00 00 00 00 00 00 64 61 74 61 00 00 00 00 00 00 00 00 00 00 00 00</nowiki></pre>
The last four bytes (the rightmost <code>00 00 00 00</code> in this case) represent a ''little endian integer'' which Source uses as the sample index at which the file should be looped. (Tested in: {{p2}}{{csgo}}) To set the loop point to the audio position at <code>x</code> seconds of a 44100 Hz mono or stereo file, represent <code>x * 44100</code> in hexadecimal, reverse the byte order and use that instead of the above last four bytes. Example: To set the loop point at 2.6 seconds from the beginning, replace the last four bytes of the above with <code>2.6 * 44,100 = 114,660 = [1BFE4]_hex = [E4 BF 01 00]_le</code>.
{{tip|The [[w:Windows Calculator|Windows Calculator]] can represent numbers in both decimal and hexadecimal in ''programmer mode'' (''scientific mode'' before Win7).}}
Now, to append some bytes to an existing WAV file, you can do the following.

==== Linux/MacOS {{linux}}{{macos}} ====

Put the above into a file named <code>cue.bin</code> using the script below, then run <code>cat my_nonlooping_sound.wav cue.bin > my_looping_sound.wav</code>.
The followind is a bash shell script used to generate <code>cue.bin</code>.

:{{expand|title=cue.sh|noborder=1|1=<source lang=sh>#!/bin/bash

# Wave file cue chunk according to https://www.recordingblogs.com/wiki/cue-chunk-of-a-wave-file
# Original script by SavageX; permission is granted to modify as needed.

ECHO="echo -en"
OUT="cue.bin"

function append_bytes() {
    $ECHO $1 >> $OUT
}

function append_cue() {
    OUT=$1

    # chunk ID, "cue "
    append_bytes "cue\x20"

    # size of the chunk: (12 + 24) - 8 = 28
    # Why -8? ID and size don't count.
    append_bytes "\x1C\x00\x00\x00"

    # number of data points: 1
    append_bytes "\x01\x00\x00\x00"

    # ID of data point: 1
    append_bytes "\x01\x00\x00\x00"

    # position: If there is no playlist chunk, this is zero
    append_bytes "\x00\x00\x00\x00"

    # data chunk ID
    append_bytes "data"

    # chunk start: 0
    append_bytes "\x00\x00\x00\x00"

    # block start: 0
    append_bytes "\x00\x00\x00\x00"

    # sample start: 0
    append_bytes "\x00\x00\x00\x00"
}

rm -f cue.bin
append_cue cue.bin</source>
}}

==== Windows {{windows}} ====

The following is a batch script file that appends the above bytes to the input files. Create a text file, paste the text in and save the file with the <code>.bat</code> extension. Drag-dropping non-looping WAV files on it (i. e. running the script with <code>%1, %2, ...</code> being the input files) will create looping copys ending with <code>_loop.wav</code>.
:{{Expand|title=loop_wav.bat|noborder=1|
<syntaxhighlight lang=batch>
@echo off
setlocal

rem Message for empty input
if "%~1"=="" (
    echo Please drag and drop one or multiple non-looping WAV files onto this script.
    echo For each file it will create a new copy ending with "_loop.wav" which will loop in Source, GoldSrc, and IdTech 2 games.
    pause
    exit /b
)

rem Define the names of helper files that we will need
set "chunkTxt=temp_cue_chunk.txt"
set "chunkBin=temp_cue_chunk.bin"
rem Create a temporary text file containing the cue chunk as hex values
>"%chunkTxt%" ( echo:63 75 65 20 1C 00 00 00 01 00 00 00 01 00 00 00 00 00 00 00 64 61 74 61 00 00 00 00 00 00 00 00 00 00 00 00 )
rem Convert the hex values to a binary file - that's what we will append to the WAV files
rem The certutil.exe lives in Windows/System32/ and should exist since XP
certutil -f -decodehex "%chunkTxt%" "%chunkBin%" >nul

rem Append the cue chunk to the WAV file
for %%F in (%*) do (
    copy /b "%%~F"+"%chunkBin%" "%%~dpnF_loop.wav" >nul
    echo Created looped WAV file "%%~nF_loop.wav".
)

rem Delete helper files
del "%chunkTxt%"
del "%chunkBin%"

pause
</syntaxhighlight>
}}

== Cue location ==

Your cues do not have to be at the start and end of the file. If you place them in the middle Source will start playing the sound normally, then when it reaches the end cue will loop back to the start cue. From then on only what's between the cues will play.

{{warning|It seems that the end cue maybe doesn't have any effect at all. See the [[Talk:Looping_a_Sound|Discussion]] page for more details.}}

{{bug|tested={{Team Fortress 2}}|In {{src|4}} games, in order to correctly loop an ADPCM-compressed WAV file from any location other than the beginning, the start cue's location (in samples) must be divided by 2. For instance, if your start cue is positioned at the sample 398060 for a sound in PCM format, it must be changed to 199030 for the same sound in ADPCM format.
<br>This bug doesn't impact loops that start at the beginning, as 0 divided by 2 is still 0.}}

This can be used to give a sound a "winding up" effect that only plays once (e.g. a motor starting).

==Looping an MP3==
[[File:Mp3loop.jpg|thumb|right|400px|The name of the <code>ambient_generic</code> is "MP3".]]
In {{src|4.1}}, MP3 files can't be looped with start/end queues like a WAV. A {{ent|logic_timer}} can be a good workaround; have it start playing the sound again after it has fully played (or has played to the point desired).

This ''could'' also be done using [[User Inputs and Outputs|User I/O]] from the <code>ambient_generic</code> to itself, and an input delay (another entity will still need to be used to trigger the initial input).

{{important|In singleplayer games prior to {{portal2|4}}, pausing the game pauses entity I/O but not music, causing the timer to go out of sync and leave a gap at the end of the song before looping.}}

==See also==

* [[ambient_generic]]
* [[Sound and Music]]

==External links==

* [http://www.interlopers.net/tutorials/27356 Looping Menu Music] - An Interlopers.net Tutorial on Soundlooping

[[Category:Sound System]]
[[Category:GoldSrc Sound System]]
[[Category:Third Party Tools]]